The short answer
Open a ticket, select Add under the summary, then Linked work item. Or right-click the card on the board and select Link work item. Choose a link type, pick the other ticket, and select Link.
The link type says how the two relate. The ones to learn first are blocks / is blocked by (one cannot finish until the other does), relates to (connected, no order), and duplicates / is duplicated by (the same problem reported twice).
Step by step
From the board
- Right-click the card, or hover over it and select More actions (•••).
- Select Link work item.
- Choose a link type, then select the work items to link. To link to a ticket that does not exist yet, select Create linked work item.
- Select Link.
From the ticket
- Open the work item.
- Select Add under the summary, then Linked work item.
- Choose the link type and the other ticket, and confirm.
Atlassian notes that users need the Link work items permission, and that a Jira admin can switch linking off for a whole site. If you cannot find the option, one of those is the reason.
Which link type to choose
Atlassian's link help lists the default link types. Each comes as a pair, one for each direction:
| Link | Use it when |
|---|---|
| blocks / is blocked by | One cannot finish until the other does |
| relates to | Connected, but no order between them |
| duplicates / is duplicated by | The same problem, reported twice |
| causes / is caused by | One produced the other, such as a change that caused a bug |
| clones / is cloned by | Created by cloning (Jira adds this itself) |
The list also includes pairs such as "implements / is implemented by" and "reviews / is reviewed by". Admins can change the list, so your site may have different or fewer types.
Getting the direction right
A link reads like a sentence, from the ticket you are on: "PAY-160 is blocked by PAY-133" means PAY-160 is waiting for PAY-133. The other ticket shows the same link the other way round: "PAY-133 blocks PAY-160". Read it aloud before you save; picking the wrong direction says the opposite of what you mean.
Reading a chain of blockers
Links really pay off when work waits on work that waits on more work. Take a made-up release:
- DIG-240 "Release 4.3" is blocked by DIG-238 "Publish the new terms on the website".
- DIG-238 is blocked by DIG-235 "Legal sign-off on the new terms".
Asked "what is holding up the release?", the honest answer is not the website team. It is the legal sign-off two links away. To find it, open the blocked ticket, follow its "is blocked by" link, and keep going until you reach a ticket that is not blocked by anything. That is the one to chase.
How to remove a link
- On the board, select the linked work items icon on the card.
- Hover over the linked item you want to remove and select the Unlink icon.
- Select Unlink to confirm.
Good habits with links
- Link duplicates before closing them, so anyone who finds the duplicate is sent to the original (see delete, archive or close).
- Use "blocks" only for real blockers. If both can go ahead, "relates to" is the honest link, and the board does not look more stuck than it is.
- Say why in a comment when you add a block: "Waiting for legal to approve the wording, expected next Tuesday."
Practise following blockers
Following a chain of links is a skill, and Agile Board Practice has puzzles built around it: find the ticket that blocks a release, unblock it, and follow a chain of blocked-by links to the real hold-up, against the clock, with feedback on each answer.
Frequently asked questions
How do I link two tickets in Jira?
Open one ticket, select Add under the summary, then Linked work item. Or right-click the card on the board and select Link work item. Choose the link type and the other ticket, then select Link.
What is the difference between blocks and relates to in Jira?
Blocks means one ticket cannot finish until the other does. Relates to means they are connected but neither waits on the other.
What does is blocked by mean in Jira?
It means the ticket you are looking at is waiting for the linked ticket. The linked ticket shows the same link as blocks.
Why can't I link tickets in Jira?
You need the Link work items permission, and a Jira admin can switch linking off for the whole site. Ask your admin if the option is missing.
How do I remove a link between tickets?
On the board, select the linked work items icon on the card, hover over the link and select Unlink, then confirm.