Send issues to Linear

Connect an app, step by step

1. In Linear

   Make a personal API key

   Signed in as the account bugs will be filed as, go to Settings → Security & access → Personal API keys and create a new key. Name it qarunbook. If Linear asks what the key may do and which teams it may reach, give it full access and the team bugs go to.

   Copy the key. Linear shows it only this once.

2. In qarunbook

   Open the app's Linear settings

   Open the app, choose App configuration, then the Integrations tab, and choose the Linear tile under Where developers fix it.

3. In qarunbook

   Paste the key, pick a team, connect

   Paste the key into Linear API key and choose Load teams. Pick the Team and choose Connect.

   The card now reads Filing to [team] [KEY]. If it says Connected. New issues go to Linear, and Done there sends the check back for a retest, you are finished.

4. In Linear

   Only if the card asks: add the webhook yourself

   When the key's account is not a Linear admin, Linear will not let qarunbook make the webhook. The card says Issues go to Linear now; finish the webhook below so Done comes back here, and shows a webhook URL. Ask a Linear admin to go to Settings → API → Webhooks → New webhook, then:

   • paste the URL from the card;
   • tick Issues, and choose the same team;
   • save it, and copy the signing secret Linear shows.
5. In qarunbook

   Only then: save the signing secret

   Back on the card, paste Linear's signing secret into the box under the URL and choose Save secret. The card says Signing secret saved.

Check it works

1. In qarunbook

   Raise a test bug

   On any check, write a line under Issues — Test: Linear connection — and choose Add issue.

2. In Linear

   See it arrive

   Within seconds the team has a new issue, titled with the check's ref and the first line — LOGIN-03 · Test: Linear connection. It carries the check, its steps, the expected result, the platforms and who raised it, with a qarunbook link attached. The issue in qarunbook shows a Linear · ENG-123 link.

3. In Linear

   Move it to Done

   Move it to Done, or any other state of the Completed type in your workflow.

4. In qarunbook

   See it come back

   The issue now reads Fixed by [name] via Linear and sits under Needs retest, and whoever raised it has been told to look again. Confirm the fix, or reopen it, as usual.

How it works

Each app connects to one Linear team. When anyone raises an issue on the app — in the runbook, from Slack or email, over MCP or through the API — it is filed in that team as the account that owns the key, with the check's steps, the expected result, the platforms it affects and a link back.

When the Linear issue moves to a completed state, qarunbook marks its issue fixed, exactly as an admin choosing Mark fixed would: the check reads retest on the platforms it affects, and whoever raised it is told to look again. Cancelling an issue in Linear is not a fix and changes nothing here.

Good to know

• Only issues raised after connecting are filed. Existing ones are left as they are.
• Linear receives bugs, not your test plan: checks and sections stay in qarunbook, and nothing from Linear creates them.
• Screenshots and recordings stay in qarunbook, behind the link on the Linear issue — their links expire, so they are not copied.
• A live app's priority carries across: urgent, high, medium and low map to Linear's own.
• Reopening in qarunbook does not reopen in Linear, and nothing in Linear ever reopens an issue here. Fixing in qarunbook first is fine — the later Done in Linear is ignored.
• The key is stored encrypted and never shown again — the card shows only its last four characters. To use another, or another team, choose Change.
• The REST API returns the link on every issue as linear (identifier and url), or null.
• Disconnect removes the webhook qarunbook made. Issues already filed keep their links.