F 15 Linear Export

Status: 🟢 ready to test Owner: Adilet Last updated: 2026-05-08 Last verified on production: —

Goal

An admin configures Linear (API key + team + project + status mapping) through the admin UI, then exports issues from Hackorda to Linear in single mode (one issue → one Linear ticket) or group mode (multi-select several Hackorda issues → one Linear ticket with a checklist body). The external_id / external_url is stored on the issue for round-trip linking.

Actors

• Primary — Admin (configures + exports)
• Secondary — Linear API; engineering team (reads the exported tickets)

Preconditions

• Admin is signed in.
• A Linear workspace exists with at least one team and one project.
• A Linear API key with create-issue scope.

Trigger

For configuration: admin opens /app/admin/integrations → Linear card. For export: admin opens any Hackorda issue or the triage queue.

Path A — Configure Linear

Path B — Single export (one issue → one Linear ticket)

Path C — Group export (N Hackorda issues → 1 Linear ticket)

Acceptance criteria

• AC-1 — Given a valid API key + team + project + state, when admin saves, then the row exists in organization_integrations and an "Active" state card renders.
• AC-2 — Given the integration is active, when admin opens LinearExportDialog, then team / project / state are pre-filled from the saved config.
• AC-3 — Given a single export, when the API returns success, then issues.external_url matches the URL Linear returned.
• AC-4 — Given a group export of 3 issues, when the API returns success, then exactly 1 Linear ticket is created (verify via Linear UI), and 3 Hackorda issues share the same external_id.
• AC-5 — Given the integration is missing or inactive, when admin clicks "Export to Linear", then the dialog explains "Linear is not configured" and does not attempt the call.
• AC-6 — Given a Linear API error (auth fail / rate limit), when the export tries, then the dialog surfaces a friendly error and does NOT mutate issues.external_* columns.
• AC-7 — Given an issue is already exported (external_id set), when admin clicks "Export to Linear" again, then the dialog warns "Already exported as DEV-123" with options "Open in Linear" or "Re-export" (verify policy on prod).
• AC-8 — Given a non-admin caller, when they hit POST /api/admin/linear/export, then 403.

Test data / fixtures

• A scratch Linear workspace + team for QA — never export to a production Linear.
• A Hackorda cycle with at least 3 approved issues for group testing.

Negative paths

Manual QA checklist

• As admin: /app/admin/integrations → Linear card "Not configured"
• Click Configure → paste API key → Test → green
• Pick team, project, default state → Save → "Active"
• Open any approved issue → "Export to Linear" button visible
• Click → dialog pre-fills team/project/state
• Confirm → toast with DEV-XXX, click "Open" → new tab to Linear ticket
• Verify Linear ticket title matches Hackorda issue title; description has Hackorda link
• Verify issues.external_id, external_url populated in DB
• On the issues list, multi-select 3 issues → "Export as group"
• Confirm → toast with DEV-YYY for the parent
• Open the Linear ticket → body has checklist of 3 sub-items linking back to Hackorda issues
• Verify all 3 Hackorda issues share external_id = DEV-YYY
• Try to export a non-admin → button hidden
• Disconnect Linear → "Export to Linear" disabled / hidden
• Re-configure with bad key → next export fails gracefully

Automated test outline

test.describe("F-15 linear export", () => {
  test("configure → test → save", async ({ page }) => { /* mock Linear */ });
  test("single export updates external_*", async ({ request }) => { … });
  test("group export shares external_id", async ({ request }) => { … });
  test("non-admin 403", async ({ request }) => { … });
  test("graceful auth_failed", async ({ request }) => { /* mock 401 */ });
});

Code references

• UI:
  • src/components/admin/integrations/LinearIntegrationCard.tsx
  • src/components/test-cycles/admin/linear/LinearExportDialog.tsx
• Pages: src/app/app/admin/integrations/page.tsx
• API:
  • src/app/api/admin/integrations/linear/route.ts (GET/PUT/DELETE config)
  • src/app/api/admin/integrations/linear/test/route.ts
  • src/app/api/admin/linear/status/route.ts
  • src/app/api/admin/linear/export/route.ts
• Hooks: src/hooks/test-cycles/linear.ts, src/hooks/test-cycles/integrations.ts
• Lib: src/lib/integrations/linear.ts (thin GraphQL fetch wrapper)
• Schema: organization_integrations (provider_slug='linear'), issues.external_id, issues.external_url, issues.external_synced_at, issues.external_status

Events emitted (proposed)

• integration.configured — { provider: 'linear', team_id, project_id }
• integration.tested — { provider, success, error_code }
• integration.disconnected
• issue.exported_to_linear — { issue_ids: [...], mode: 'single' \| 'group', external_id, exported_by }

Open questions / known gaps

• Multi-tenant Linear: v1 is single-tenant. Per-org Linear config is deferred (feature-matrix.md §3.9).
• Linear → Hackorda webhook to pull external_status back is deferred. Today, external_status is set once at export time and never updated.
• Re-export semantics (overwrite vs. update) are not nailed down.
• No "unlink from Linear" action (just clear external_* in DB).