Send issues to Jira — qarunbook API docs

Testers raise issues in qarunbook; developers work in Jira. Connect the two and every bug lands in your Jira project, and moving it to Done there puts the check back in front of the person who found it.

Before you start

A Jira Cloud site, like https://yourteam.atlassian.net, with a project to file bugs in.
The Atlassian account bugs should be filed as — a shared bot account reads best. It needs permission to create issues in the project. If it is a Jira admin, qarunbook sets up the way back for you.
To be an admin of the app in qarunbook. Jira is on every plan.

Connect an app, step by step

In Atlassian account
Create an API token
Signed in as the account bugs will be filed as, go to id.atlassian.com → Security → API tokens and choose Create API token. Name it qarunbook, pick an expiry, and choose Create.
Choose Copy. Atlassian shows the token only this once.
In qarunbook
Open the app's Jira settings
Open the app, choose App configuration, then the Integrations tab, and choose the Jira tile under Where developers fix it.
In qarunbook
Give your site, email and token
Fill in Jira site (https://yourteam.atlassian.net), the Email of the account the token belongs to, and paste the token into Jira API token.
In qarunbook
Load projects, pick one, connect
Choose Load projects. Pick the Project and the Issue type — Bug is chosen for you when the project has one — and choose Connect.
The card now reads Filing to [project] as Bug. If it says Connected. New issues go to Jira, and Done there sends the check back for a retest, you are finished.
In Jira
Only if the card asks: add the webhook yourself
When the token's account is not a Jira admin, Jira will not let qarunbook make the webhook, so the card shows a webhook URL and a secret instead. Ask a Jira admin to go to Settings (⚙) → System → WebHooks → Create a WebHook, then:
- paste the URL into URL and the secret into Secret;
- under Issue related events, enter the JQL project = YOURKEY and tick Issue → updated;
- choose Create.

Check it works

In qarunbook
Raise a test bug
On any check, write a line under Issues — Test: Jira connection — and choose Add issue.
In Jira
See it arrive
Within seconds the project has a new issue, QA-1: Test: Jira connection, with the check, its steps, the expected result, the platforms and a link back to qarunbook. The issue in qarunbook shows a Jira · KEY-1 link.
In Jira
Move it to Done
Drag it to Done on the board, or change its status.
In qarunbook
See it come back
The issue now reads Fixed by [name] via Jira 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 Jira Cloud project. 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 project as QA-13: the first line of the issue.

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 choosing Mark fixed would. Moving between statuses that are not Done changes nothing here.

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 one that does not check out is refused. From a webhook's first signed delivery on, unsigned ones are refused too. 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.
Jira receives bugs, not your test plan: checks and sections stay in qarunbook. A bug raised on a check carries that check's section, steps and expected result into Jira.
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 token is stored encrypted and never shown again — the card shows only its last four characters. To use another, choose Change.
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.