Linked issues

{{< details >}}

• Tier: Free, Premium, Ultimate
• Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated

{{< /details >}}

{{< history >}}

• Changed minimum required role from Reporter (if true) to Guest in GitLab 17.0.

{{< /history >}}

Linked issues are a bi-directional relationship between any two issues and appear in a block below the issue description. You can link issues in different projects.

The relationship only shows up in the UI if the user can see both issues. When you try to close an issue that has open blockers, a warning is displayed.

[!note] To manage linked issues through our API, see the Issue links API.

Add a linked issue

Prerequisites:

• You must have the Guest, Planner, Reporter, Developer, Maintainer, or Owner role for both projects.

To link one issue to another:

1. In the Linked items section of an issue, select the add linked issue button ({{< icon name="plus" >}}).

2. Select the relationship between the two issues. Either:

   • relates to
   • blocks
   • is blocked by

3. Input the issue number or paste in the full URL of the issue.

   Issues of the same project can be specified just by the reference number. Issues from a different project require additional information like the group and the project name. For example:

   • The same project: #44
   • The same group: project#44
   • Different group: group/project#44

   Valid references are added to a temporary list that you can review.

4. When you have added all the linked issues, select Add.

When you have finished adding all linked issues, you can see them categorized so their relationships can be better understood visually.

You can also add a linked issue from a commit message or the description in another issue or MR. For more information, see crosslinking issues.

Remove a linked issue

In the Linked items section of an issue, select the remove button ({{< icon name="close" >}}) on the right-side of each issue token to remove.

Due to the bi-directional relationship, the relationship no longer appears in either issue.

Access our permissions page for more information.

Blocking issues

{{< details >}}

• Tier: Premium, Ultimate
• Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated

{{< /details >}}

When you add a linked issue, you can show that it blocks or is blocked by another issue.

Issues blocked by other issues have an icon ({{< icon name="entity-blocked" >}}) next to their title, shown in the issue lists and boards. The icon disappears when the blocking issue is closed or their relationship is changed or removed.

If you try to close a blocked issue using the "Close issue" button, a confirmation message appears.