Jira Linked Issues: A Practical Guide to Issue Relationships

Need clearer project context? Learn how jira linked issues reveal dependencies, connect related work, and prevent blockers. Read now to improve your workflow.

Jira linked issues are connections between related work items that show how tasks, bugs, risks, and dependencies affect one another. When those relationships are missing, teams lose context, duplicate effort, and discover blockers too late. A developer may fix a bug without seeing the feature it affects. A project manager may approve work without noticing an unresolved dependency. Over time, the issue tracker becomes a list of disconnected tasks rather than a clear picture of the project. But here's the truth: linking issues takes seconds, while recovering lost context can take hours. This guide explains Jira issue relationships, when to use each link type, how to create them, and how to keep links useful as your project grows.

You will also see practical examples for bugs, requirements, sub-tasks, releases, and cross-team dependencies. By the end, you can choose the right relationship instead of adding links randomly.

What Are Jira Linked Issues?

Jira linked issues are separate Jira work items connected through a relationship such as blocks, is blocked by, relates to, duplicates, or is duplicated by. Each link explains how one issue connects to another without merging them into one item.

For example, a payment bug might be linked to a checkout improvement with the relationship blocks. The bug remains its own issue, while the link tells the team that the improvement cannot move forward safely until the bug is resolved.

Jira product screenshot

How Issue Links Differ From Parent-Child Relationships

Jira offers several ways to connect work. Issue links describe a relationship between separate items. A parent issue and its sub-tasks describe a work hierarchy.

Parent and sub-task: Breaks one larger piece of work into smaller actions.
Epic and story: Groups related delivery work under a broader outcome.
Issue link: Shows dependency, duplication, reference, or another connection between issues.

Imagine a mobile checkout epic containing several stories. A security bug may sit outside that epic but still block one of its stories. A linked issue captures that cross-cutting relationship without forcing the bug into the epic.

Common Jira Link Types

Link type	When to use it
blocks	One issue prevents progress on another issue.
is blocked by	One issue cannot progress because another issue remains unresolved.
relates to	Two issues share context but neither directly depends on the other.
duplicates	One issue repeats the same problem described elsewhere.
is duplicated by	Another issue repeats the current issue.
causes	One issue creates a failure, defect, or consequence represented by another.
is caused by	The current issue exists because of another issue.
clones	A similar issue is created for another context, team, or environment.

Available link types can vary by Jira configuration. Your administrator may add, rename, or remove relationships, so always check the wording shown in your project.

How to Link Issues in Jira

Open the issue you want to connect. Choose the issue that needs additional context, such as a bug, story, task, or risk.
Find the linking action. Open the issue's action menu and select Link, Link issue, or the equivalent option in your Jira layout.
Choose the relationship. Select a precise link type, such as blocks, is blocked by, or relates to.
Identify the other issue. Enter its issue key, summary, or another available search term. For example, enter PAY-248 to find a payment defect.
Add a short explanation. If the relationship needs context, add a comment such as “Checkout release depends on the gateway timeout fix.”
Save the link. Jira should display the connection in the issue's linked-issues area.
Check both sides. Open the connected issue and confirm that the reverse relationship appears correctly.

Here's why the reverse check matters: Jira usually shows the relationship from both perspectives. If you accidentally choose blocks instead of is blocked by, the wording may confuse everyone reviewing the work later.

Linking Issues From the Issue View

The issue view is the simplest option when you are already investigating a bug or planning a task. Open the action menu, select the linking option, choose the relationship, and search for the related issue.

Use this method when you have one clear relationship. For example, while reviewing APP-317, you discover that it depends on API-94. Link the application issue as is blocked by the API issue, then add a concise explanation.

Linking Issues During Issue Creation

Some Jira configurations let you add links while creating an issue. This approach works well when a new bug appears during testing and you already know which story or release item it affects.

For example, create a bug for a failed login test and connect it to the login story with relates to. If the failed test prevents release approval, connect it to the release task with blocks as well.

Linking Issues With Bulk Actions or Automation

Bulk actions can help when several issues share the same relationship. Automation can also create or update links when a workflow event occurs.

Use automation carefully. A rule that links every reopened bug to the same task can produce clutter quickly. Start with a narrow condition, test it on a small project, and review the result before expanding it.

Choosing the Right Relationship

The best link type describes the practical effect of one issue on another. Ask a simple question: “If this issue changes, how does the other issue respond?” The answer usually points to the correct relationship.

Use “Blocks” for Real Delivery Dependencies

Use blocks when work cannot reasonably continue until another issue is resolved. A service migration may block a reporting feature because the feature depends on the new service endpoint.

Do not use blocks merely because two issues are important. Importance does not create dependency. If the team can complete both items independently, relates to may be more accurate.

Use “Relates To” for Shared Context

Relates to is appropriate when issues concern the same feature, customer journey, technical area, or investigation. For example, a usability improvement and a translation request may relate to the same settings page without either one preventing the other.

This relationship is broad, so add a clear comment when the connection is not obvious. A short explanation helps future readers understand why the link exists.

Use “Duplicates” to Reduce Repeated Work

When two issues describe the same problem, mark one as a duplicate of the other. Keep the issue with better reproduction steps, clearer ownership, or stronger history as the primary item.

Before closing a duplicate, check whether it contains unique details. A customer report may include an environment clue that the older issue does not have. Copy important context into the surviving issue before closing the duplicate.

Use “Causes” When You Are Tracing a Failure

Cause-and-effect links help during incident reviews and defect investigations. A configuration change may cause a failed deployment, while a missing validation rule may cause incorrect invoice totals.

These links are especially useful when the team needs to understand why a problem happened. They should support a clear explanation rather than replace one.

Practical Examples of Linked Issues

Concrete examples make relationships easier to apply. Consider a retail application preparing for a seasonal promotion.

Example 1: A Bug Blocks a Feature

The team is building a one-click checkout feature. During testing, engineers discover that expired cards trigger an application error. The defect becomes APP-402, while the feature is APP-377.

Link APP-402 to APP-377 using blocks. The relationship tells the product team that completing the feature without fixing the defect creates release risk.

Example 2: Two Issues Describe One Problem

A customer reports that email receipts arrive twice. Later, a support agent creates another issue after seeing the same behavior. The second report duplicates the first.

Mark the newer issue as duplicates. Preserve any additional details, such as the customer account type or browser version, before closing it.

Example 3: Separate Teams Share a Dependency

The mobile team needs a new authentication endpoint from the platform team. The mobile story cannot pass integration testing until the endpoint exists.

Link the mobile story as is blocked by the platform task. This creates visibility across teams and gives the dependency a clear owner.

Example 4: Related Work Without a Direct Blocker

A team is improving search filters while another team updates product categories. Both changes affect the catalog experience, but either team can work independently.

Use relates to. A blocking link would exaggerate the dependency and could distort planning discussions.

How Linked Issues Affect Planning and Reporting

Issue links become valuable when they influence daily decisions. A sprint board may show that a story is in progress, yet a linked blocker explains why progress has stopped.

For example, a team with ten open stories may appear healthy by issue count. After reviewing relationships, you may find that four stories depend on one unresolved API task. The dependency view changes the priority conversation immediately.

Dependencies and Sprint Planning

Review linked issues before a sprint begins. Look for stories that are blocked by unfinished work, cross-team handoffs, pending approvals, or technical investigations.

If a story has a critical blocker, the team can reorder work, assign an owner to the dependency, or move the story to a later sprint. This is more reliable than discovering the problem during the final testing day.

Release Readiness

Before a release, inspect unresolved issues connected through blocks, causes, and is blocked by. A release checklist may look complete while a linked defect remains open elsewhere.

For instance, a completed checkout story linked to an unresolved payment defect deserves additional review. The link gives release managers a practical reason to investigate.

Reporting and Traceability

Reports can reveal clusters of related issues. A high number of duplicates may point to poor search habits or unclear intake rules. Many blockers connected to one team may indicate a capacity problem.

Use these patterns as conversation starters. A link shows a relationship, while a human review explains what action the team should take.

Best Practices for Managing Issue Relationships

Choose the narrowest accurate relationship. Use blocks for a genuine dependency and relates to for shared context.
Write useful comments. Explain the reason for a less obvious connection in one or two sentences.
Review links during refinement. Remove outdated relationships and confirm that active dependencies still matter.
Keep duplicates under control. Search before creating a new issue, especially for recurring bugs.
Assign ownership to blockers. A link creates visibility, while an owner creates accountability.
Avoid link inflation. Connecting every vaguely similar issue makes important relationships harder to find.
Use consistent terminology. Agree on what your team means by “blocked,” “related,” and “duplicate.”
Check permissions and workflow rules. Some teams cannot create certain links or transition connected issues without additional permissions.

The best part? You do not need hundreds of links to gain value. A small set of accurate relationships can expose the dependencies that matter most.

Jira Linked Issues Solution: ONES.com

ONES.com product screenshot

Value Proposition

ONES.com combines project management and knowledge management in one platform powered by ONES Assistant. ONES Project is a Jira alternative for teams that need connected planning, workflows, reporting, and issue context. ONES Wiki is a separate knowledge management product and a Confluence alternative.

The platform supports cloud, on-premise, private cloud, and air-gapped deployments. A free plan supports up to 30 seats, and the self-hosted versions provide feature parity with the cloud version.

Core Capabilities

Scattered dependencies → Jira-compatible workflows: Teams can preserve familiar issue relationships and workflow patterns while organizing connected work in one project environment.
Hidden blockers → Built-in reporting: Reporting helps teams review issue status, dependencies, and delivery trends without relying on disconnected add-ons.
Rigid issue structures → Custom workflows and fields: Teams can adapt statuses, fields, and transitions to reflect their approval paths and relationship rules.
Unclear sprint commitments → Sprint management: Sprint planning tools help teams examine related work before committing to delivery dates.
Repeated manual updates → Automation: Workflow automation can reduce routine transitions and notifications when defined conditions occur.
Too many plugins → Native feature coverage: Core project functions are available within the platform, reducing the need to assemble several separate extensions.
Restricted-network requirements → On-premise and air-gapped deployment: Teams with strict infrastructure controls can run the platform in an environment that matches their operational requirements.
Separate project and knowledge context → ONES.com platform structure: Teams can use ONES Project and ONES Wiki together when they need planning work and knowledge content connected across the same platform.

Application Scenarios

Cross-team product development: A product team can connect feature work to API tasks, test defects, and release risks. Managers can then review which relationships threaten the next milestone.

Regulated or restricted environments: An engineering group operating in an air-gapped network can manage workflows and linked work without moving project activity into a public cloud environment.

Growing teams replacing Jira: A team evaluating a Jira alternative can retain familiar issue-based planning while reducing dependence on multiple plugins and custom integrations. ONES Project and ONES Wiki are sold separately, so teams can select the product combination that matches their needs.

Common Challenges With Issue Relationships

Challenge: The Team Uses “Relates To” for Everything

Why it happens: The relationship feels safe when people are uncertain about dependency.

Solution: Ask whether one issue can proceed without the other. If progress truly stops, use blocks or is blocked by. If both can proceed independently, keep relates to.

Challenge: Links Become Outdated

Why it happens: A task changes scope, a blocker gets resolved, or a release plan moves forward.

Solution: Review linked issues during backlog refinement and release planning. Remove obsolete links and update comments when the relationship changes.

Challenge: Duplicate Issues Keep Appearing

Why it happens: People search by different terms or create issues quickly during support and testing.

Solution: Add a short search step to your intake process. When duplicates appear, keep the strongest issue active and preserve unique details from the others.

Challenge: A Blocker Has No Clear Owner

Why it happens: Linking an issue creates visibility, but it does not automatically assign responsibility.

Solution: Assign the blocking issue to a team or person. Add a target date when the dependency affects a sprint or release commitment.

FAQs

What are linked issues used for in Jira?

Linked issues show relationships between separate work items. You can use them to identify blockers, connect related investigations, mark duplicate reports, trace causes, and show cross-team dependencies. They are useful when two issues need to remain separate while still sharing important context. For example, a platform task can block a mobile story without becoming a sub-task of that story.

What is the difference between a linked issue and a sub-task?

A sub-task is part of a parent issue and usually represents one piece of completing that larger item. A linked issue remains independent and may belong to another team, project, sprint, or workflow. Use sub-tasks for internal breakdown, such as design, coding, and testing. Use links for relationships such as dependency, duplication, cause, or shared context.

Should I use “blocks” or “relates to”?

Use blocks when one issue prevents meaningful progress on another. Use relates to when the issues share context but can proceed independently. For example, an unfinished API endpoint may block a mobile integration story. Two improvements affecting the same screen may simply relate to each other.

Can Jira issues link across projects?

Yes, Jira can support links between issues in different projects when permissions and project settings allow it. Cross-project links are useful for shared services, platform dependencies, security reviews, and release coordination. Before using them, confirm that both teams understand the relationship and can access the connected issue.

How many links should an issue have?

There is no universal limit that makes an issue healthy or unhealthy. A complex release risk may need several accurate links, while a simple task may need none. Focus on usefulness rather than volume. If the issue contains many vague relationships, remove weak connections and keep the links that change planning, ownership, or risk decisions.

Conclusion

Jira linked issues give your team a practical way to show dependencies, duplicates, causes, and shared context. Start with the relationship that best describes the effect between two issues, then add a short explanation when the connection needs interpretation.

Review links during refinement, sprint planning, and release checks. That small habit can expose a blocked feature before it becomes a missed deadline, just as removing duplicate reports can prevent wasted investigation.

But here's the truth: the value comes from accurate relationships, not from linking everything. Use clear link types, assign owners to blockers, and consider a connected platform such as ONES.com when your project and knowledge workflows need a more unified operating model.