Send issues to Jira — qarunbook API docs

Testers raise issues in qarunbook; developers work in Jira. Connect the two and a failed check lands in your Jira project, 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 Jira Cloud project. When anyone raises an issue on the app — in the runbook, over MCP or through the API — it is filed in that project as QA-13: the first line of the issue, with the check's steps, the expected result, the platforms it affects and a link back. The issue in qarunbook shows a Jira link to it.

When the Jira issue moves to any status in Jira's Done category — Done, Closed, Resolved, whatever your workflow calls it — 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. Moving between statuses that are not Done changes nothing here.

Connect an app

Make an API token for the Atlassian account issues should be filed as: id.atlassian.com → Security → API tokens → Create API token.
In qarunbook, open the app, choose Configure, then the Integrations tab, and find Jira. You need to be an admin of the app.
Give your Jira site (https://yourteam.atlassian.net), the account's email and the token, choose Load projects, pick the project and the issue type — Bug unless you choose otherwise — and Connect.

The token is stored encrypted and never shown again — the settings show only its last four characters. Issues are filed as whoever owns the token, so a shared bot account in Jira reads best. That account needs permission to create issues in the project.

The webhook

If the account is a Jira admin, qarunbook makes the webhook for you, limited to the project and signed with a secret, and there is nothing else to do. Otherwise the settings show a webhook URL and a secret: in Jira, go to Settings → System → WebHooks → Create a WebHook, paste the URL and the secret, tick Issue → updated, limit it with the JQL project = YOURKEY, and save.

Every delivery must carry the unguessable token in its URL. A webhook with a secret also signs each delivery (the X-Hub-Signature header, an HMAC-SHA256 of the body), and a signature that does not check out is refused. From a webhook's first signed delivery on, unsigned ones are refused too — the webhook qarunbook makes is given the secret, so it is held to signing from its first event. 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 Jira issue — their links expire, so they are not copied.
A live app's priority carries across when the project has a priority field: urgent, high, medium and low map to Highest, High, Medium and Low, or the nearest your scheme has.
Reopening in qarunbook does not reopen in Jira, and nothing in Jira ever reopens an issue here. Fixing in qarunbook first is fine — the later Done in Jira is ignored.
The REST API returns the link on every issue as jira (key and url), or null.
Disconnecting removes the webhook qarunbook made. Issues already filed keep their links.