Send issues to Linear — qarunbook API docs

Testers raise issues in qarunbook; developers work in Linear. Connect the two and a failed check lands in your Linear team, and closing it there puts the check back in front of the tester who found it.

The shape of it

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

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

Connect an app

In Linear, make a personal API key: Settings → Security & access → Personal API keys.
In qarunbook, open the app, choose Configure, then the Integrations tab, and find Linear. You need to be an admin of the app.
Paste the key, choose Load teams, pick the team, and Connect.

The key is stored encrypted and never shown again — the settings show only its last four characters. Issues are filed as whoever owns the key, so a key belonging to a shared bot account in Linear reads best.

The webhook

If the key belongs to a Linear admin, qarunbook makes the webhook for you and there is nothing else to do. Otherwise the settings show a webhook URL: in Linear, go to Settings → API → Webhooks → New webhook, paste the URL, tick Issues, choose the same team, and save. Then copy the signing secret Linear shows into qarunbook and choose Save secret.

Every delivery is checked against that secret (the Linear-Signature header) and must be under two minutes old. A redelivered event fixes an issue once and tells the reporter once.

Good to know

Only issues raised after connecting are filed. Existing ones are left as they are.
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 REST API returns the link on every issue as linear (identifier and url), or null.
Disconnecting removes the webhook qarunbook made. Issues already filed keep their links.