Link Jira issues

Link a post to the Jira issues where the work happens. When an issue is done, the post moves to Shipped and its voters get the status email. When an issue is in progress, the post moves to In progress, and when it is resolved as Won't do or deleted, to Closed. You don't install a Jira app or sign in with Atlassian: you add one webhook in Jira.

Jira Cloud only. 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 Jira, and click Create the Jira endpoint. You get a webhook URL and a secret. The secret is shown once: keep the page open until you have pasted it in Jira.

2. Add the webhook in Jira

  1. In Jira, open Settings (the gear), then System, then WebHooks, then Create a WebHook (Atlassian's guide). You need to be a Jira admin.
  2. URL: the webhook URL from FigVote.
  3. Secret: the secret from FigVote. Don't use Jira's Generate secret button: FigVote must know the secret to check each delivery.
  4. Issue events: tick created, updated and deleted. You can add a JQL filter, for example project = ABC, to send only the projects you link issues from.
  5. Save.

If you lose the secret, click New secret in FigVote and paste the new one in the webhook in Jira. Until you do, FigVote refuses Jira's deliveries.

3. Link issues to posts

In the dashboard, click Jira on a post and paste the issue key, for example ABC-123, or its address, for example https://acme.atlassian.net/browse/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 Jira" with the issue key only, without a link or a title.

Issues are matched by their key. If you move an issue to another Jira project, it gets a new key: link it again.

What moves a post

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

  • Done (any status in the Done category): the post moves to Shipped if it was Open, Planned or In progress.
  • Done with the resolution Won't Do, Won't Fix, Duplicate, Cannot Reproduce, Declined, Rejected, Canceled or Obsolete (or a Done status with one of these names), or the issue deleted: the post moves to Closed if it was Open, Planned or In progress.
  • In progress (any status in the In Progress category, like In Review): the post moves to In progress if it was Open, Planned or Shipped. A Closed post stays closed.
  • Back to To Do: the post doesn't move.
  • A post linked to several issues waits until none of its other issues is in progress or to do. Then it ships, or it closes if every other issue was closed without being done too. An issue that Jira 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.

Deleting a whole Jira project doesn't send anything for its issues (a Jira limit): close or unlink those posts by hand.

Security and data

  • Every delivery is checked against the X-Hub-Signature header Jira computes with your secret. Anything unsigned or signed with another secret is refused, and so is an issue key that isn't linked to a post of this project: it changes nothing.
  • Jira signs the body only, without a separate time header. FigVote reads the event time inside the signed body: a delivery more than a day old is refused, and an event older than the last one seen for an issue changes nothing. So an old delivery sent again does nothing.
  • The secret is stored encrypted and is never shown again.
  • From each delivery FigVote keeps only the issue's status category and the event time. Summaries, descriptions and people are not stored.
  • A delivery that Jira retries changes nothing the second time.