Jira issues rarely exist alone. A bug may come from a story, an improvement may depend on another task, and a duplicate ticket can split attention across your team. When those relationships stay hidden, people repeat work, miss dependencies, and struggle to understand what should happen next.
The problem gets worse as a project grows. A simple search may reveal several related issues, yet teammates still need to open each one and guess how they connect. That slows triage and makes handoffs harder.
But here's the truth: linking Jira issues takes only a few clicks when you know which relationship to choose. This guide shows you how to create links, select the right link type, edit or remove them, and use links to keep work moving.
Meta Title: How to Link Issues in Jira: Step-by-Step Guide 2025
Meta Description: Learn how to link Jira issues, choose the right relationship, fix common errors, and manage dependencies clearly with this practical step-by-step guide.
How to Link Issues in Jira
Linking issues in Jira means creating a visible relationship between two work items, such as a dependency, duplicate, parent task, or related bug.
You can link issues while viewing an issue, during issue creation, or through Jira’s bulk-edit tools. The exact labels may vary between Jira Cloud and Jira Data Center, but the workflow remains similar.
Step 1: Open the issue you want to connect
Open the issue that will act as your starting point. For example, you might open a login bug that prevents a user story from being completed.
Check the issue key before continuing. A key such as APP-142 identifies the exact issue you want to connect.
Step 2: Find the linking option
Look for the issue actions menu, often shown as three dots near the issue title. Choose Link or Link issue.
Some Jira layouts show the option under an More menu. If you cannot find it, your project administrator may have changed the screen layout or restricted the permission.
Step 3: Choose the relationship
Jira will ask you to select a link type. Choose the relationship that accurately explains how the two issues connect.
- blocks: The current issue prevents another issue from progressing.
- is blocked by: The current issue cannot progress until another issue is completed.
- relates to: The issues share useful context but have no direct dependency.
- duplicates: The current issue repeats another issue.
- is duplicated by: Another issue repeats the current issue.
- clones: The current issue copies another issue for a separate workstream.
- is cloned by: Another issue was copied from the current issue.
Step 4: Enter the other issue
Enter the key of the issue you want to connect. You can usually type part of the key or summary and choose a matching result.
For example, link APP-142 to APP-119 when the login defect blocks the account recovery story. Verify the summary before saving.
Step 5: Add a useful comment
A comment is optional, but it can clarify why the link matters. Write a short explanation such as, “The API change must be deployed before this checkout test can pass.”
A clear note helps someone understand the relationship without opening several issues or asking for extra context.
Step 6: Save the link
Click Link, Save, or the equivalent confirmation button. Jira should display the relationship in the issue’s linked-issues area.
Open the connected issue if you want to confirm the reverse relationship. Jira commonly shows the paired wording automatically, such as “blocks” on one issue and “is blocked by” on the other.
Choosing the Right Jira Link Type
The link type should describe the relationship, not merely show that two issues mention the same feature. A precise link gives your team useful information during planning and triage.
| Situation | Recommended link | Example |
|---|---|---|
| One issue must finish before another can move forward | blocks / is blocked by | An infrastructure change blocks a deployment task |
| Two issues describe the same problem | duplicates / is duplicated by | Two customers report the same checkout error |
| Two issues share context without dependency | relates to | A design request relates to a usability bug |
| A separate issue was created from an existing one | clones / is cloned by | A regional rollout clones a global implementation task |
When to use “blocks”
Use blocks when work cannot reasonably continue until another issue changes or finishes. This relationship is especially useful for release planning.
Imagine a payment service upgrade and a checkout validation task. If the validation task depends on the upgrade, the upgrade issue blocks the validation issue.
When to use “relates to”
Choose relates to when issues belong to the same conversation but do not have a strict order. This avoids creating false dependencies.
For example, a mobile navigation improvement may relate to a customer feedback issue. The two items provide context for each other, but either could be completed first.
When to use “duplicates”
Use duplicates when two issues describe the same work or defect. Keep the issue with better details, clearer ownership, or stronger history as the primary item.
After linking duplicates, add a comment explaining which issue should remain active. Then close the redundant issue using your team’s normal resolution process.
When to use “clones”
Choose clones when a similar issue needs separate ownership, timing, or scope. A cloned issue may look similar while requiring different acceptance criteria.
For instance, a security fix for the web application may be cloned for a mobile application. The work resembles the original, yet each team manages its own delivery.
Other Ways to Create Issue Relationships
Opening one issue at a time is the simplest method, but Jira offers several useful alternatives. The best option depends on how many issues you need to connect and where you are working.
Link issues while creating a new issue
When creating an issue, look for a linked-issue field or add the relationship after the issue is saved. This works well when you already know the related issue key.
For example, while creating a regression bug, you can connect it to the story that introduced the behavior. That preserves the relationship from the beginning.
Use the issue details panel
Some Jira configurations show linked issues directly in the issue details area. Select the add-link control, choose a relationship, and search for the second issue.
This approach is convenient during triage because you can connect issues without leaving the screen you are reviewing.
Link several issues through bulk changes
If many issues need the same relationship, use Jira’s bulk-change feature when your permissions allow it. Select the relevant issues, choose the linking action, and provide the target issue.
Review the selection carefully first. A bulk action can create incorrect relationships across many issues when one filter includes unrelated work.
Use Jira automation for repeated relationships
Automation can create or update links when a defined event occurs. For example, a rule might link a newly created subtask to a parent issue or connect a follow-up issue after a transition.
Keep automated rules narrow. A rule that links every issue with a matching label can create noise when labels are used casually.
Managing and Reviewing Linked Issues
Creating a link is only the beginning. Your team gets the most value when links remain accurate, visible, and easy to interpret during everyday work.
Review links during planning
During sprint planning, inspect blocked issues before committing to them. A team may plan ten tasks, yet two could depend on an unfinished platform change.
Finding that relationship early lets you reorder work, assign an owner, or adjust the sprint goal before the problem affects delivery.
Update links when plans change
Dependencies can disappear after a technical decision changes. Remove an outdated “blocks” relationship instead of leaving it as historical clutter.
To remove a link, open the linked-issues area, find the relationship, and choose the remove or delete control. Jira may ask you to confirm the action.
Search for linked work with JQL
Jira Query Language can help you locate issues using link-related conditions, depending on your Jira version and available functions.
A common starting point is searching for a specific issue key, then reviewing its linked issues manually. Advanced teams may use link functions provided by Jira or marketplace extensions.
Always test a query in a narrow project or filter before using it in a dashboard. A broad query can return more work than your team expects.
Show relationships on boards and dashboards
Boards help with status, while linked issues explain why an item is waiting. Add filters, dashboard gadgets, or custom views that surface blocked work.
For example, a delivery dashboard can highlight open issues that block a release. The team can then focus on the constraint rather than treating every task as equally urgent.
Using ONES.com for Connected Project Work
Jira issue links are useful when your team needs lightweight relationships inside a development workflow. Larger programs may also need planning, dependency visibility, requirements, and cross-team coordination in one workspace.
ONES.com can support that broader workflow by giving teams a central place to organize related project work. Consider it when Jira links feel too narrow for the way your teams plan and deliver.
Capabilities that can support connected workflows
- Requirements management: Connect product needs with planned implementation work and delivery outcomes.
- Project planning: Organize milestones, activities, and ownership across several teams.
- Task and issue tracking: Give teams a shared view of work status, responsibility, and priority.
- Dependency visibility: Identify relationships that may affect schedules or release readiness.
- Custom workflows: Adapt statuses and approval steps to match your operating process.
- Permission controls: Limit project visibility and editing rights for different groups.
- Reports and dashboards: Turn project activity into views that support planning meetings and reviews.
- Team collaboration: Keep conversations and decisions close to the work they explain.
The best part? You do not need every relationship to look identical. A development team may need technical issue links, while a product group may need connections between requirements, milestones, and delivery tasks.
Before choosing a broader platform, map your current workflow. Write down where teams lose context, which relationships need reporting, and where handoffs usually slow down.
Jira Issue-Linking Best Practices
Good linking is a habit supported by clear team rules. Without those rules, people may select “relates to” for every relationship, making important blockers difficult to find.
Agree on link definitions
Create a short internal guide that explains each link type with a practical example. Your team should know the difference between “blocks,” “relates to,” and “duplicates.”
For example, define “blocks” as a relationship that affects sequence or progress. Define “relates to” as context without a required order.
Link at the moment of discovery
Add the relationship when you notice it during refinement, testing, or triage. Delaying the task increases the chance that the connection will be forgotten.
A tester who finds that a bug belongs to a specific story should link both issues immediately. That small action saves time during the next planning session.
Keep link comments specific
A useful comment explains the reason and consequence. “Related” adds little value, while “The authentication change must reach staging before this test can run” gives clear context.
Review duplicate issues regularly
Duplicate tickets can divide comments, votes, and ownership. During backlog reviews, compare similar issues and keep the clearest item active.
Link the duplicate before closing it so anyone who finds the older ticket can follow the relationship.
Avoid excessive linking
Too many low-value links create visual noise. Link issues when the relationship changes decisions, sequencing, ownership, or understanding.
For example, five issues may mention the same feature, but only one may truly block the release. Highlight that meaningful dependency first.
Common Challenges
The Link option is missing
Problem: You open the issue actions menu but cannot find a linking command.
Solution: Ask a Jira administrator to check your project permissions, issue layout, and screen configuration. The required permission may be restricted to specific roles.
The wrong relationship was selected
Problem: An issue shows “relates to” even though work cannot continue without the other issue.
Solution: Remove the inaccurate link and create a new one using “blocks” or “is blocked by.” Add a short comment explaining the dependency.
The other issue cannot be found
Problem: Jira does not return the issue you expect when you search by summary.
Solution: Search with the exact issue key, such as WEB-287. Also check project permissions, issue status, and whether the issue belongs to a project you can access.
Linked issues create too much noise
Problem: An issue contains many relationships, but nobody can see which ones matter.
Solution: Remove obsolete links, close duplicates, and reserve “relates to” for meaningful context. Use comments to explain high-impact relationships.
A link does not change workflow status
Problem: You link a blocking issue, but Jira does not automatically move or flag either issue.
Solution: A link describes a relationship; it does not always control workflow behavior. Use automation, board rules, or dashboard filters when you need visual alerts or transitions.
FAQs
Can I link issues in different Jira projects?
Yes, if your Jira permissions allow access to both issues and cross-project linking is available in your configuration. Open one issue, choose the link action, and enter the key from the other project. Cross-project links are useful when a platform team blocks work in a product project. Check access settings if Jira cannot find the second issue.
What is the difference between linking and making a subtask?
A subtask is a child item that belongs directly to a parent issue and usually follows the parent’s structure. A linked issue remains an independent item with its own owner, status, and planning needs. Use a subtask for smaller pieces of one deliverable. Use a link when two separate issues have a dependency, duplicate relationship, or shared context.
Can I link an issue after it has been closed?
In many Jira configurations, you can link an issue after closure if you have permission to edit or manage its relationships. This is useful when a later bug reveals a connection to an earlier release. Your workflow or project settings may restrict changes to completed issues, so contact an administrator if the link action is unavailable.
Does linking two issues copy comments or status?
No. A link connects the issues and displays their relationship, but it does not automatically copy comments, fields, attachments, or workflow status. If both issues need the same update, add it separately or create an automation rule. Be careful with automatic updates because a status change in one issue may not always make sense for the other.
Can I create custom link types in Jira?
Jira administrators can often create or manage link types, especially in Jira Data Center and certain administrative configurations. A custom relationship may help when standard options do not describe your workflow. Keep custom names simple and define their direction clearly. Too many link types can confuse the team and reduce reporting consistency.
Conclusion
Linking Jira issues takes a few steps: open an issue, choose the link action, select the correct relationship, identify the other issue, and save the connection.
Use “blocks” for real dependencies, “duplicates” for repeated work, “clones” for separate copies, and “relates to” for useful context without a strict sequence. Review links during planning and remove relationships that no longer matter.
When hidden dependencies cause delays, clear issue relationships give your team an immediate view of what connects, what waits, and what deserves attention. Start with one active project, agree on link definitions, and make accurate linking part of your normal Jira workflow.
