Link Linear issues

Link a post to the Linear issues where the work happens. When an issue is completed, the post moves to Shipped and its voters get the status email. When an issue is started, the post moves to In progress, and when it is canceled, to Closed. You don't install a Linear app or sign in with Linear: you add one webhook in Linear.

Included in Solo and Pro. Only the project owner can set up the webhook.

1. Create the endpoint in FigVote

Open your project, then Integrations, then Linear, and click Create the Linear endpoint. You get a webhook URL.

2. Add the webhook in Linear

  1. In Linear, open Settings, then API, then Webhooks, then New webhook (Linear's guide). You need to be a workspace admin.
  2. URL: the webhook URL from FigVote.
  3. Data change events: tick Issues only. Pick all public teams or the teams you link issues from.
  4. Save, then copy the signing secret shown on the webhook's page.

3. Paste the signing secret in FigVote

Back in Integrations, paste the secret in Signing secret and click Save secret. Until then, FigVote refuses every delivery. The Integrations page shows the time of the last delivery once Linear sends one. If you create a new webhook in Linear, paste its secret the same way: it replaces the old one.

4. Link issues to posts

In the dashboard, click Linear on a post and paste the issue ID, for example ABC-123, or its address, for example https://linear.app/acme/issue/ABC-123. A post can be linked to up to 10 issues. Links are private unless you tick Show on the public post. Public links show up under the post as "Tracked in Linear" with the issue ID only, without a link or a title.

Issues are matched by their ID. If you move an issue to another team, Linear gives it a new ID: link it again.

What moves a post

Only a change of the issue's status counts. Editing its title, labels or assignee doesn't move anything.

  • Completed (a status of the Completed type, like Done): the post moves to Shipped if it was Open, Planned or In progress.
  • Canceled, or marked as a duplicate: the post moves to Closed if it was Open, Planned or In progress.
  • Started (like In Progress or In Review): the post moves to In progress if it was Open, Planned or Shipped. A Closed post stays closed.
  • Back to Triage, Backlog or Todo: the post doesn't move.
  • A post linked to several issues waits until none of its other issues is started or not started yet. Then it ships, or it closes if every other issue was canceled too. An issue that Linear has sent nothing about since you linked it doesn't hold the post back.
  • Optional: tick "Also start a changelog draft" to get an unpublished changelog entry for each shipped post. Nothing is published without you.

Security and data

  • Every delivery is checked against the Linear-Signature header with your project's signing secret. Anything unsigned or signed with another secret is refused.
  • A delivery whose timestamp is more than a minute away from now is refused, so an old delivery can't be sent again.
  • The secret is stored encrypted and is never shown again.
  • From each delivery FigVote keeps only the issue's status type and its last update time. Titles, descriptions and people are not stored.
  • A delivery that Linear retries changes nothing the second time.