ContextQMD
Back to Gitlabhq

Linked items

doc/user/work_items/linked_items.md

18.11.27.0 KB
Original Source

{{< details >}}

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

{{< /details >}}

Linked items create bi-directional relationships between work items, helping you visualize and manage dependencies across your entire workflow.

With linked items, you can connect various work items including issues, epics, tasks, and objectives to show relationships between them.

These connections help everyone understand how individual pieces of work relate to each other and to larger strategic initiatives.

Ways to use linked items

You can use linked items to solve several planning and coordination challenges.

The following examples show how linked items help teams work together more effectively.

Track dependencies

{{< details >}}

  • Tier: Premium, Ultimate

{{< /details >}}

Clearly identify work that blocks or is blocked by other items.

When you link items with a blocking relationship:

  • Teams can immediately see what other work they depend on.
  • Status updates flow automatically between linked items.
  • Warnings appear when closing items that have open blockers.
  • Teams can avoid delays by addressing dependencies proactively.

This visibility helps coordinate work across teams and reduces bottlenecks.

Connect strategic goals with implementation details

Use linked items to connect high-level planning with day-to-day execution.

When you link strategic objectives to tactical tasks:

  • Teams understand how their work contributes to larger goals.
  • Stakeholders can trace progress from strategy to implementation.
  • Everyone gains visibility into how individual efforts support the broader vision.
  • Changes in strategy can be quickly traced to affected implementation work.

This connection between levels creates alignment and purpose across the organization.

Organize cross-functional initiatives

Link related work across different teams and projects to coordinate complex initiatives.

When you use linked items for cross-functional work:

  • Each team can work in their own area while maintaining connections to related work.
  • Dependencies between specialized teams become visible.
  • Status updates flow automatically between related items.
  • Teams can coordinate their efforts without constant meetings.

This coordination helps break down silos and ensures all aspects of the initiative stay in sync.

Types of linked items

GitLab supports linking various types of work items:

  • Issues help you track tasks, bugs, and features and can be linked to show dependencies between discrete pieces of work.
  • Epics let you manage cross-functional initiatives, show dependencies, and connect strategic planning to execution across multiple teams or projects. Available in the Ultimate tier.
  • Tasks provide lightweight tracking for smaller units of work and can be linked to other items to show relationships or dependencies in a project.
  • Objectives and key results help connect strategic goals with execution details, ensuring that day-to-day work remains aligned with higher-level organizational priorities.
  • Incidents represent service disruptions or outages that need urgent restoration and can be linked to related work items for better tracking of operational issues and their impact on planned work.
  • Test cases integrate test planning directly into your GitLab workflows, letting teams document testing scenarios and track requirements in the same platform where they manage code. Available in the Ultimate tier.

Relationship types

When linking items, you can specify the type of relationship:

  • Relates to: Indicates a general relationship between items.
  • Blocks: Shows that an item prevents progress on another item.
  • Is blocked by: Shows that an item cannot proceed until another item is resolved.

Common tasks with linked items

Learn how to create and manage relationships between your work items with these common procedures.

Add a linked item

Prerequisites:

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

The general process for adding linked items is similar across all work item types:

  1. Go to the work item you want to modify.
  2. At the bottom of the description, find the Linked items section of the work item.
  3. Select Add.
  4. Select the relationship type: relates to, blocks, or is blocked by.
  5. Enter the reference for the item to link. You can:
    • Enter # or & (depending on item type) followed by the item's number.
    • Enter text to search for the item by title.
    • Paste the full URL of the item.
  6. Select Add to confirm.

Alternatively, you can add linked items using quick actions:

  • /relate
  • /blocks
  • /blocked_by

For detailed information specific to each work item type, see the relevant documentation:

Remove a linked item

Prerequisites:

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

To remove a linked item:

  1. Go to the work item you want to modify.
  2. At the bottom of the description, find the Linked items section of the work item.
  3. For each linked item, select Remove ({{< icon name="close" >}}).

The bi-directional relationship is removed from both items.

Alternatively, you can remove a linked item using the /unlink quick action.

Configure linked item display preferences

{{< history >}}

  • Display options for linked items expanded in GitLab 18.10.

{{< /history >}}

You can configure what information is displayed in the Linked items section, so that you can focus on what matters most for your workflow.

[!note] When you change the information displayed in a work item, you change it for all work items in your projects and groups.

  1. At the top-right corner of the Linked items section header, select Display options ({{< icon name="preferences" >}}).

    By default, all options and fields are visible.

  2. To change the displayed information, turn the following toggles on or off:

    • For display options:
      • Show closed items
    • For fields displayed:
      • Status
      • Assignee
      • Labels
      • Weight
      • Milestone
      • Iteration
      • Dates
      • Health
      • Blocked/Blocking