JIRA - Linking Issues

Jira - Linking Issues

Linking issues in Jira is a powerful feature for establishing and visualizing relationships between different work items. This is crucial for managing dependencies, tracking duplicates, grouping related tasks, and understanding the overall context of your project work. Effective linking improves traceability and team coordination.

How to Link Issues

To create a link between issues, follow these general steps:

Navigate to one of the issues you want to link (this will be the ‘source’ issue).
On the issue’s detail view screen, look for an option to link issues. This could be a dedicated ‘Link issue’ button (often depicted with a chain link icon), an option within an actions menu (e.g., ’…’ or ‘More actions’), or an ‘Add link’ control within a ‘Linked issues’ section.
Clicking this option will open a ‘Link issue’ dialog box.

Inside the ‘Link issue’ dialog:

Choose the Link Type: Select the type of relationship that best describes how the current issue relates to the issue(s) you’re about to link. Common types include ‘blocks’, ‘is blocked by’, ‘relates to’, ‘duplicates’, ‘clones’, etc. The available link types are configured by your Jira administrator.
Select the Issue(s) to Link: Search for the issue(s) you want to link to. You can typically search by the issue key (e.g., PROJECT-123), or by typing keywords from its summary. Jira will display matching issues, and you can select one or more.
Add a Comment (Optional): You can add a comment to provide more context about why you are creating this link. This comment will be visible with the link.
Confirm the Link: Click the ‘Link’ button to establish the relationship.

Once linked, the relationship will be displayed in the ‘Linked issues’ section on the view screens of both issues. This section will show the type of link, the key and summary of the linked issue, and often its current status, providing a quick overview of related work.

Deleting an Issue Link

If a link is no longer relevant or was made in error, you can remove it:

Navigate to either of the issues involved in the link.
Locate the ‘Linked issues’ section.
Find the specific link you wish to remove. Hover over it or look for an associated action icon (like a trash can or ’…’ menu) next to the link.
Click the ‘Delete’ or ‘Remove link’ option. Jira may ask for confirmation before removing the link.

Deleting a link only removes the relationship between the issues; it does not delete the issues themselves.

Common Link Types and Their Usage

Understanding the semantics of different link types is key to effectively managing dependencies and relationships:

Blocks / Is Blocked By: This defines a direct dependency. For example, ‘Issue A’ blocks ‘Issue B’ means Issue B cannot be completed until Issue A is resolved. Conversely, ‘Issue B’ is blocked by ‘Issue A’.
Relates to: This is a general, non-blocking relationship indicating that two issues are connected in some way (e.g., they affect the same module, or are part of a similar theme).
Duplicates / Is Duplicated By: Used when one issue reports the same problem or request as another. Typically, one issue will be closed as a ‘duplicate’ of the other.
Clones / Is Cloned By: Indicates that one issue was created as a copy of another. This is often used for templating tasks or when an issue needs to be re-created in a different project.
Other custom link types: Your Jira administrator can define custom link types specific to your organization’s workflows (e.g., ‘tested by’, ‘causes’).

Best Practices for Linking Issues

Be precise with your choice of link type to accurately reflect the relationship between issues. This clarity helps everyone understand dependencies.
Regularly review issues with ‘blocks’ or ‘is blocked by’ links, especially during daily stand-ups or planning sessions, to ensure that blockers are being addressed and work can progress.
Use linking to provide essential context. While links are useful, they don’t replace the need for clear communication in issue descriptions, comments, or team discussions.
Avoid over-linking. Only create links that add genuine value and help in understanding or managing the work.