How to Connect Linear & Run Native QA Sprints

Linear is built for blazing speed and developer focus. However, Linear deliberately omits test case management, step-by-step test execution runners, and release quality gates. Klority acts as the native QA execution layer for Linear: your developers stay 100% inside Linear, while your QA engineers get full test suite management and 1-click defect synchronization.

Architecture Overview: Zero Infrastructure Overhead

Unlike legacy tools that rely on fragile webhooks, brittle Zapier zaps, or heavy AWS Lambdas, Klority communicates directly with Linear's official GraphQL API via our high-speed Fastify backend.

flowchart LR
    A["Linear Sprint: ENG-102"] -->|1-Click Sync| B["Klority Backlog & QA Cycle"]
    B -->|Execute Test Run| C{"Step Result"}
    C -->|Pass| D["Update Pass Rate %"]
    C -->|Fail| E["Bedrock AI Auto-Diagnose"]
    E -->|1-Click Log & Sync| F["Created in Linear: ENG-108"]
    F -->|Clickable Badge| G["Linear & Klority Backlinked"]
    D & F --> H["Release Readiness Quality Gate: 🟢 GO / 🔴 NO-GO"]
        

• Zero Tab Switches for Devs: Developers receive QA defects directly in their Linear triage or sprint board with full reproduction steps. They never need a Klority account.
• Direct GraphQL Monolith: Outgoing mutations execute against https://api.linear.app/graphql in <1.2 seconds.
• Strictly Conditional: Projects without Linear enabled run completely offline with zero external network overhead.
• AES-256-CBC Encryption: Linear API tokens are encrypted at rest in PostgreSQL.

Step 1: Obtain a Linear Personal API Key

Connecting your Linear workspace takes less than 30 seconds. You only need a Personal API Key with member permissions.

1. Log into your workspace at linear.app.
2. In the bottom-left sidebar, click your profile avatar and navigate to Settings.
3. Under Account, click Security & Access.
4. Scroll down to the Personal API Keys section and click Create Key.
5. Name the key Klority QA Bridge and click Create.
6. Copy the generated key (formatted as lin_api_...). Store it securely.

Step 2: Configure Linear in Klority Project Settings

Enable Linear synchronization on a per-project basis within Klority:

1. Open Klority and navigate to your target project.
2. In the project navigation tabs, click Project Settings (gear icon).
3. Select the Linear Sync tab.
4. Toggle the switch: "Enable Linear Sync for this Project".
5. Paste your lin_api_... key into the Linear Personal API Key input.
6. Click "Test & Fetch Teams". Klority immediately validates the key against Linear's API and returns:
   ✓ Connected to Linear as: Your Name (your.email@company.com)
7. Select your Default Linear Team (e.g., Engineering (ENG)) where newly discovered bugs should be created.
8. Click Save Linear Settings.

Step 3: 1-Click Sync Linear Issues to Klority Backlog

Bring Linear tasks, user stories, and acceptance criteria into Klority to attach test cases:

1. Navigate to Project Management → Backlog.
2. Click the "Sync Linear" button in the header toolbar.
3. Klority pulls open Linear issues, mapping title, description (with parsed Markdown and images), priority, and assignee.
4. Each synced task displays a clickable Linear tag (e.g., [ENG-102]) linking directly to Linear.

Step 4: Execute Test Cycles in Keyboard-Flow

QA engineers can now execute structured test runs against the release candidate:

1. Navigate to QA → Test Cycles and click Create Test Cycle (e.g., v2.4 Staging Regression).
2. Select test cases from your repository or generate new cases using Bedrock AI Test Draft directly from Linear acceptance criteria.
3. Launch the Test Execution Runner.
4. Use keyboard shortcuts to mark steps:
   • P → Pass
   • F → Fail
   • B → Block

Step 5: 1-Click Defect Logging Back to Linear

When a test assertion fails, logging a defect requires zero context switching:

Clicking "Log & Sync to Linear" creates the ticket in Linear (e.g., ENG-108). The Klority test card immediately attaches a live clickable badge: [Linear: ENG-108]. In Linear, developers get an automatic link back to the exact Klority test run.

Step 6: The Release Readiness Quality Gate

Before shipping to production, engineering leaders and release managers no longer need to ask "Are we good to release?" in Slack.

Navigate to Test Reports → Release Readiness to inspect the live audit log, environment breakdown, and linked Linear ticket status list.

Security & Data Privacy FAQ