Skip to content
Unblockd
Start free
Menu
Help topics · Jira

Connect Jira to Unblockd

Link a Jira project to an Unblockd project and its issues come in as tasks, with their status kept in step.

Updated · About the Jira integration

On this page

What Unblockd reads

Unblockd reads your Jira projects and the issues in the ones you link to an Unblockd project. You choose which issues to bring in; each becomes a task under a deliverable, with a link back to Jira as its first proof. From then on its status follows Jira.

It’s read-only. Unblockd never creates, edits, or deletes issues in Jira. The one thing it adds in Jira is a webhook that tells it when something changes.

An issue that’s blocked in Jira opens a blocker your team sees first. Nothing reaches your sponsor until someone on your team chooses to share it.

The access token is encrypted before it’s stored. How Unblockd handles your data.

Before you start

  • In Unblockd, a workspace admin connects Jira, once for the whole workspace. Members see it in Settings but can’t connect or disconnect it. Anyone on the team can then link it to a project.
  • In Jira: An Atlassian account that can browse the Jira projects you want to link. If your site restricts third-party apps, a site admin may need to allow Unblockd.

Connect Jira

  1. Open Connected toolsSign in to Unblockd and open Settings, then Connected tools.
  2. Press Connect beside JiraFind Jira under Most used, or press Show all 33 tools, or type its name in the search box. Then press Connect on its row.
  3. Approve access in JiraAtlassian shows the permissions Unblockd requests and asks which site to use it on. Unblockd connects one Jira site per workspace. Unblockd requests read:jira-work (read Jira projects and issues), manage:jira-webhook (keep one webhook that tells Unblockd when issues in your linked projects change), and offline_access (stay connected without asking you to sign in again).
  4. Back in UnblockdYou come back to Connected tools, which says “Jira is connected. Next, link it to a project from the project’s Sources tab.” Its row shows the account and Connected.

manage:jira-webhook lets Unblockd keep one webhook on your site that covers your linked projects. Jira webhooks last 30 days, so Unblockd checks it daily and extends it when fewer than 10 days remain.

Link it to a project

  1. Open the project’s Sources tabOpen the project from Projects, then its Sources tab.
  2. Press Link a sourceIt’s under the list of linked sources. If more than one tool is connected, choose Jira under Tool.
  3. Pick the Jira projectUnder Jira project, pick the one this Unblockd project runs on. Only projects the connection can see are listed, and ones already linked here are left out.
  4. Choose where items landUnder New items land in, choose a deliverable, or leave Choose each time. It’s the first choice when you bring items in, and where new items go if automatic import is on.
  5. Press LinkThe Jira project appears in the Sources list, ready to bring items in.

Starting a new project? On New project, open “Bring work in from a tool”, choose Jira and the project, and leave “Bring in open items as tasks” on to start with its open issues. It’s linked as the project is created.

Bring in items

  1. Press Bring in itemsOn the project’s Sources tab, press Bring in items on the Jira project’s row. Unblockd lists the open issues that aren’t in this project yet.
  2. Choose the deliverableUnder Add them under, choose the deliverable they belong to. Each item comes in as a task under it.
  3. Choose the issuesTick the issues you want, search by key or title, or press Choose all. Then press Bring in. Up to 50 come in at a time; run it again for more.

New issues can also come in on their own. An admin turns on Bring in new items from linked sources in Settings, then Automations, and each source can opt out or pick its deliverable from its ⋯ menu, under New items. Up to 25 come in per sync, checked every hour.

How sync works

Jira sorts every status into a category, so the category decides, after the blocked check. Each issue becomes the first status that matches:

Flagged, or a status with Blocked, On hold, or Impeded in its name
Becomes: Blocked
A status in the Done category
Becomes: Done
A status in the In Progress category
Becomes: In progress
A status in the To Do category, or anything else
Becomes: To do

When something changes, Jira tells Unblockd. Unblockd then reads that issue again through Jira’s API before changing anything, so a forged or replayed call can change nothing on its own. There’s nothing to sync by hand.

  • Done in Jira finishes the task in Unblockd, because the link back to Jira already counts as proof. A task that needs a sign-off stays where it is until the sign-off is recorded.
  • Blocked in Jira marks the task Blocked and opens a blocker for your team only, and posts to your team’s chat channels if you’ve connected any. Someone on your team confirms it and can turn it into an ask for your sponsor. If the issue moves on in Jira, the task follows; the blocker stays open until your team resolves it.
  • A title changed in Jira changes in Unblockd too. A tool never puts a task In review: that needs a reviewer chosen in Unblockd.
  • Tasks from a tool stay with your team. Your sponsor sees each deliverable’s progress, not the tasks under it.

Disconnect and revoke access

  1. Press DisconnectIn Settings, then Connected tools, press Disconnect on Jira’s row.
  2. ConfirmIf it’s linked to projects, Unblockd first says how many projects it will unlink. Press Disconnect Jira to confirm, or Keep.
  • Deleted: the connection, its stored access, and every Jira project linked through it, across all your Unblockd projects, along with the webhooks Unblockd added in Jira.
  • Kept: tasks already brought in stay as ordinary tasks with their history and proof links. They stop following Jira. Connect again and relink the same Jira project, and they follow it again.
  • Atlassian keeps the access you granted until it's removed. Remove Unblockd from the connected apps in your Atlassian account settings.

To stop one project following Jira without disconnecting it for everyone, open the linked Jira project’s ⋯ menu on the Sources tab and choose Unlink. Its tasks stay, but stop following Jira.

Troubleshooting

Needs reconnecting
What to do: Jira turned down Unblockd’s access, for example because it was revoked or the person who connected it left. The row says “Reconnect to keep it in sync.” An admin presses Reconnect and approves access again; linked projects and their tasks carry on.
Retrying
What to do: The row says “Couldn’t reach it on the last try. It will try again.” Jira didn’t answer the last time Unblockd tried. Nothing is lost; the next sync picks up where it stopped.
A project is missing
What to do: Only projects the connected account can see are listed. Check its access in Jira, or reconnect with an account that can see it.
Only an admin can connect
What to do: “Only a workspace admin can connect or disconnect tools.” Ask an admin, or have one change your role in Settings, then Members.
The connection link expired
What to do: “That connection link expired or was started by someone else. Try again from here.” Start again from Connected tools and finish within 10 minutes.
A different account
What to do: “This workspace is linked to a different account for that tool. Disconnect it first.” Each workspace connects one Jira account. Disconnect the old one first.
Coming soon
What to do: A tool that shows Coming soon instead of Connect can’t be connected yet.

Still stuck? Press Report a problem on Jira’s row in Connected tools, or choose Report a problem with Jira from a linked project’s ⋯ menu. One tap sends the tool and what the row shows about the connection (never a key or token) to the Unblockd team, and someone replies by email. You can send 5 reports every hour, or write to hello@unblockd.ai any time.

Connect Jira now

Open Connected tools in Unblockd and press Connect beside Jira. You’ll need to be a workspace admin.

Open Connected tools