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 detail page, Send to Jira creates a ticket in your chosen project containing the impact, WCAG criteria, failing selector, affected-page count, and a link back to the issue.
• Inbound. When the Jira ticket moves to a Done-category status, the TAC issue transitions to fixed — pending verification. Only a re-scan can move an issue to verified; a ticket being closed is a claim, not proof.
• Status comments. When a re-scan verifies the fix (or the issue is archived), TAC posts a comment on the linked ticket so the dev team sees the outcome without leaving Jira.

TAC stays the source of truth; the Jira ticket is a working copy for the team doing the remediation.

1 — Create an API token

The integration authenticates against your own Jira Cloud site with an Atlassian API token:

1. Sign in at id.atlassian.com → Security → API tokens → Create API token.
2. Copy the token. Like TAC tokens, it is shown once.

Tickets and comments are created as the Atlassian account that owns the token, so many teams prefer a dedicated service account (e.g. accessibility-bot@yourcompany.com) over a personal one. The account needs permission to browse projects and create issues in the target project.

2 — Connect in the dashboard

Only owners and admins can manage the integration.

1. Open Settings → Integrations → Issue trackers.
2. Enter your Jira site (acme.atlassian.net), the account email, and the API token, then click Connect. TAC validates the credentials against Jira before storing them encrypted (AES-GCM).
3. Pick the project that new accessibility tickets should be created in and save.

Push is active immediately: issue detail pages now show a Send to Jira button in the sidebar. Tickets are created with the project’s Task issue type when it exists, otherwise the first creatable non-subtask type.

3 — Add the webhook (inbound sync)

Jira Cloud does not allow API tokens to register webhooks, so a Jira admin adds one manually:

1. After the project is saved, the settings card shows an Inbound status sync URL of the form https://…/api/webhooks/jira/<integration-id>/<secret>. Copy it.
2. In Jira, go to Settings → System → WebHooks → Create a WebHook.
3. Paste the URL, tick the Issue → updated event, and save.

The URL’s trailing segment is a random secret and is the only credential on this endpoint — treat the URL like a password. TAC compares it in constant time and ignores events for tickets it didn’t create, so the webhook can safely fire for the whole project.

Skip this step and the integration is push-only (the settings card shows a push only badge); ticket status then has no effect on TAC issues.

4 — Day-to-day flow

1. Triage an issue in TAC and click Send to Jira. The sidebar now links to the ticket (e.g. ENG-421), and the push is recorded on the issue’s activity timeline. One ticket per issue per tracker — sending twice returns the existing link.
2. The team fixes the underlying problem and moves the ticket to Done (any status whose category is Done).
3. TAC marks the issue fixed — pending verification and notes it came from Jira.
4. The next scan verifies the fix. TAC posts the verification outcome as a comment on the ticket.

If both Linear and Jira are connected, the issue sidebar offers both, and status comments fan out to every linked ticket.

Disconnecting

Settings → Integrations → Issue trackers → Jira → Disconnect deletes the stored credentials and webhook secret. Existing ticket links remain on issues for reference, but push, comments, and inbound sync all stop. Remember to also delete the webhook in Jira admin — with the secret gone, its deliveries are rejected, but there is no reason to keep it firing.

Troubleshooting

Symptom	Likely cause	Fix
Connect fails with a credentials error	Wrong email/token pair, or the token was revoked.	Re-create the API token and reconnect. The email must be the Atlassian account that owns the token.
Send to Jira returns a Jira error	The service 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 TAC issue didn’t change	Webhook not created, wrong event ticked, or the URL was truncated when pasting.	Check the webhook exists with Issue → updated ticked and that the full URL (including the secret) was pasted.
Issue shows fixed — pending verification but never verified	That’s by design — only a scan can verify.	Run a scan of the affected site; the verification result is also commented back on the ticket.