Jira sync
The Accessibility Company can push issues to Jira Cloud as tickets and listen for status changes coming back:
- Push. From any issue’s page, Send to Jira creates a ticket in your chosen project with the impact, rule, WCAG criteria, failing selector, affected-page count, site, and a link back to the issue.
- Inbound. When the Jira ticket moves to a Done-category status, the issue moves to fixed, pending verification. Closing a ticket never marks the issue verified: a closed ticket is a claim, not proof, and a scan has to confirm it.
- Comments. When the issue is verified, by a scan (Verify now, the verification after a linked pull request merges, or two full scans in a row that do not find the problem) or by someone marking it verified in the dashboard, and when an issue logged by hand is archived, a comment goes on the linked ticket so the team sees it without leaving Jira.
The issue in your workspace stays the record; the Jira ticket is a working copy for the team doing the fix.
Jira sync is on every plan.
1. Create an API token
Section titled “1. Create an API token”The integration signs in to your own Jira Cloud site with an Atlassian API token:
- Sign in at id.atlassian.com → Security → API tokens → Create API token.
- Copy the token. Atlassian shows it only once.
Tickets and comments are created as the Atlassian account that owns
the token, so many teams use a dedicated service account (for example
accessibility-bot@yourcompany.com) rather than a personal one. The
account needs permission to browse projects, create issues and add
comments in the target project.
2. Connect in the dashboard
Section titled “2. Connect in the dashboard”Only owners and admins can manage the integration.
- Open Settings → Connections.
- Under Jira, enter your Jira site (
acme.atlassian.net), the account email and the API token, then choose Connect. We check the credentials with Jira before storing them, encrypted (AES-GCM). - Pick the project new accessibility tickets should be created in, and choose Save project.
Push works straight away: issue pages show a Send to Jira button in the sidebar. Tickets use the project’s Task issue type when it has one, otherwise the first issue type that can be created and isn’t a subtask.
3. Add the webhook (inbound sync)
Section titled “3. Add the webhook (inbound sync)”Jira Cloud doesn’t let API tokens register webhooks, so a Jira admin adds one by hand:
- Once the project is saved, the settings card shows an Inbound
status sync URL of the form
https://…/api/webhooks/jira/<integration-id>/<secret>. Use Copy URL. - In Jira, go to Settings → System → WebHooks → Create a WebHook.
- Paste the URL, tick the Issue → updated event, and save.
The URL’s last segment is a random secret and is the only credential on this endpoint, so treat the URL like a password. We compare it in constant time and ignore events for tickets we didn’t create, so the webhook can safely fire for the whole project.
Saving the project again creates a new secret, and the old URL stops working: paste the new one into the Jira webhook.
Skip this step and the integration is push-only: ticket status then has no effect on issues. The settings card can’t see whether the webhook exists in Jira, so check it there.
4. Day-to-day flow
Section titled “4. Day-to-day flow”- Triage an issue and choose Send to Jira. Members and above can
send. The sidebar now links to the ticket (for example
ENG-421). Each issue gets one ticket per tracker: sending again shows the existing link. - The ticket is titled
[a11y]and the issue’s title. - The team fixes the problem and moves the ticket to Done (any status whose category is Done).
- The issue moves to fixed, pending verification, with a note on its activity naming the ticket.
- A scan confirms the fix: Verify now on the issue once the fix is deployed, the verification after a linked pull request merges (see GitHub), or two full scans in a row. The issue is then verified, and the ticket gets a comment saying so.
If both Linear and Jira are connected, the issue’s sidebar offers both, and comments go to every linked ticket. See Linear sync.
Disconnecting
Section titled “Disconnecting”Settings → Connections → Jira → Disconnect deletes the stored credentials and webhook secret. Existing ticket links stay on issues for reference, but push, comments and inbound sync all stop. Delete the webhook in Jira’s admin settings too: with the secret gone its deliveries are refused, but there is no reason to keep it firing.
Troubleshooting
Section titled “Troubleshooting”| Symptom | Likely cause | Fix |
|---|---|---|
| Connect fails with a credentials error | Wrong email and token pair, or the token was revoked. | Create a new API token and connect again. The email must be the Atlassian account that owns the token. |
| Send to Jira returns a Jira error | The account can’t create issues in the selected project, or the project has required custom fields. | Grant Create issues permission, or make required fields optional for the Task type. |
| Ticket moved to Done but the issue didn’t change | No webhook, the wrong event ticked, the URL cut short when pasting, or the project was saved again since. | Check the webhook exists with Issue → updated ticked, and that its URL matches the one on the settings card in full. |
| Issue shows fixed, pending verification but never verified | By design: only a scan verifies. | Use Verify now on the issue once the fix is live. |