Skip to content

Linear sync

The Accessibility Company can send issues to Linear as tickets and listen for their status changing:

  • Push. From any issue’s page, Send to Linear creates a ticket in your chosen team with the impact, rule, WCAG criteria, failing selector, affected-page count, site, and a link back to the issue.
  • Inbound. When the Linear ticket moves to a completed state, the issue moves to fixed, pending verification. Only a scan can mark it verified: a completed ticket is a claim, not proof.
  • 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 ticket so the team sees it without leaving Linear.

The issue in The Accessibility Company stays the record; the Linear ticket is the working copy for the team doing the fix.

Linear sync is on every plan.

The integration works with a Linear personal API key:

  1. In Linear’s settings, create a personal API key.
  2. Copy it, ready to paste into the dashboard.

Tickets, comments and the webhook are created as the Linear user who owns the key, so many teams use a dedicated account (for example accessibility-bot@yourcompany.com) rather than a personal one. The key needs to create issues and comments in the team you choose, and to create a webhook for that team.

Only owners and admins can manage the integration.

  1. Open Settings → Connections.
  2. Under Linear, paste the API key and choose Connect. We check the key with Linear before storing it, encrypted (AES-GCM).
  3. Choose the team new accessibility tickets should go to, then Save team.

Saving the team also registers a webhook on that team in Linear, so there is nothing to set up on the Linear side. The card then reads Connected to your team, and issue pages show Send to Linear in the sidebar.

If Linear cannot create the webhook (the key lacks the permission, or Linear cannot reach us), the team is still saved and push works. The card shows a push only badge, and the message after saving says why. Fix the cause, then choose the team again to retry.

The webhook is signed: Linear signs every delivery with a secret only it and we hold, we check the signature, and we only act on tickets we created for your workspace.

  1. Triage an issue and choose Send to Linear. 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.
  2. The ticket is titled [a11y] and the issue’s title.
  3. The team fixes the problem and completes the ticket (any workflow state of Linear’s Completed type, such as Done).
  4. The issue moves to fixed, pending verification, with a note on its activity naming the ticket.
  5. 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.

Cancelling a ticket in Linear does not change the issue, and nor does moving a ticket back out of Completed. If the problem turns out to be still there, Verify now on the issue reopens it.

If both Linear and Jira are connected, the issue’s sidebar offers both, and comments go to every linked ticket. See Jira sync.

Settings → Connections → Linear → Disconnect removes the webhook from Linear and deletes the stored key and webhook secret. Existing ticket links stay on issues for reference, but push, comments and inbound sync all stop.

To change the team, disconnect and connect again.

Symptom Likely cause Fix
Connect fails saying Linear rejected the key The key was mistyped, revoked, or belongs to another Linear workspace. Create a new key and connect again.
Push only badge after saving the team Linear couldn’t create the webhook: the key lacks permission, or Linear couldn’t reach us. Use a key that can create webhooks for the team, then save the team again.
Send to Linear returns a Linear error The key’s user can’t create issues in that team, or the team has required fields. Give the user access to the team, or relax the required fields.
Ticket completed but the issue didn’t change The webhook is missing, or the ticket was cancelled rather than completed. Check the card has no push only badge, and complete the ticket.
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.