Use links to view dependencies and track related work

Azure DevOps Services | Azure DevOps Server 2022 - Azure DevOps Server 2019 | TFS 2018

By linking work items to other work items, you can track related work, view a hierarchy of work, view dependencies, and more. By linking work items to devops and other objects, you support an auto trail of changes and enable quick navigation to work items and linked objects.

Different link types are used to link to the various objects. For example, you can use Parent/Child links to support a hierarchical tree structure of work items. The Commit and Branch link types support links between work items and Git commits and branches, respectively.

Link work items to support the following goals:

• Track dependencies, related items, and work hierarchies
• Track which work items are tested by test cases and test results
• Support an audit trail of code changes and the work items they support
• Support end-to-end traceability
• Share information by linking work items to a network share, storyboard, or document.

This article describes the link types available for your use. You can link objects from the web portal or Visual Studio Team Explorer. For details on linking work items and deleting links, see Add link to work items.

Tip

You can set up automatic linking and other settings that link work items to Git commits, pull requests, builds, and more. To learn how, see the following resources:

• Cross-service overview
• Configure pipelines to support work tracking
• Drive Git development from a work item
• Link and view work items to builds and deployments.

View list of linked objects

To view the list of all objects linked to a work item, open the work item and choose the Links tab. The links tab indicates the count of all linked objects.

Linked objects are grouped under their link type, with a count within each group. You can expand or collapse each group, and sort within each group by State, Latest Update, or Comment by choosing the corresponding column title.

For example, the following Links tab shows a portion of the 64 linked objects for a work item.

Links prefaced with the red exclamation mark indicate that the build, release, or other object has been deleted. This is usually due to retention policies which automatically delete these objects after a certain time period has passed.

Work items linked to work items

There are several system link types used to link work items to each other: two tree topology, one dependency topology, and one network. Tree topology links support nested hierarchies, tree queries, and several reports. Dependent links support tracking tasks that must be completed before others can be started. And, the Related link type supports connecting work items that are at the same level.

All two-way link types are characterized by a Forward and Reverse name, such as Parent/Child and Duplicate/Duplicate Of. When you link using one of these names, the linked work item is updated to include a link with the corresponding link type. For example, if you add a Parent link to a work item, the linked work item contains a Child link.

As a quick reference guide, use the following link types as indicated:

• Use the Duplicate link type when two work items have been created that essentially capture the same information; close one of the work items and keep the other one active
• Use the Parent/Child link types when you want to break down work items into smaller items—for example, break down features into stories, or stories into tasks
• Use Predecessor-Successor link types when you want to track tasks that must be completed before others can be started; this link type is most often used when you plan work using Project
• Use the Related link type when the work items being linked are at the same level—such as two user stories that define features that overlap one another—or to link work items that are defined in different projects or managed by different teams.

For guidance on choosing link types, review the Link type reference in the related notes section.

You can create links from within a work item form, from a work item that appears in a list of query results, in Microsoft Excel, or in Microsoft Project. You can also use any of the client programs for Team Foundation, such as Team Explorer and the web portal, to create links or attach files.

Also, you can use the context menu in the web portal or Team Explorer.

Note

For each work item, you can add a maximum of 1000 links to other work items.

Cross-organization work item linking

Organizations that use Azure Active Directory can link work items that exist in different projects across organizations. Use the following link types as indicated:

• Use the Consumes From/Produces For link types when you want to track dependencies of work items that are defined in different organizations and managed by different teams.
• Use the Remote Related link type when the work items being linked are defined in different organizations and managed by different teams, but don't have strong inter-dependencies.

Add a work item link

You can create links between work items by using one of the links control tabs within a work item form. The user interface to link a work item differs based on the platform, version, and client you use. To link several work items to a new or existing item, see Add link to work items.

Note

Work item forms and features available to you can differ depending on whether you open the form from the web portal or Visual Studio Team Explorer.

Browser

From the work item form, you can add a link using the Related Work section or from the Links tab.

Open a work item and choose Add link or the plus icon to add a link.

Choose Existing item to link to a work item or other object using any supported link type. Choose New item to start a link and define a new work item at the same time. For more information, see Add link to work items.

From the Related Work or Links tab, you can also complete these actions:

• View the list of objects linked to the work item
• Open an associated item or object: choose the linked item
• Delete a link: highlight it and choose the delete icon

From a query results page, you can also complete these actions:

• Link selected items to a new work item
• Link selected items to an existing work item

For more information, see Add link to work items.

Visual Studio

If you primarily work in Visual Studio, and want to link work items, you can do so in many ways. Depending on the work item form and customizations that may have been made to your work item form, you may see several Link tabs. Link tabs can be customized to allow or restrict specific link types.

Open a work item and choose the Links tab. From the links control tab you can link to new or existing work items, open the linked object, edit the link type, delete a link, or open the list of links in a query or Excel or Project.

The work item form opens in the web portal for Visual Studio 2017 and later versions. Work items aren't available from Visual Studio 2019 under the following conditions:

• If you're connected to a GitHub or third-party Git repository.
• If you're set to use the new Git Tool for Visual Studio 2019 as described in Git experience in Visual Studio.

Parent-child work item links

These features let you quickly link or change links that use the parent-child link type:

• To link backlog items to portfolio backlog items or to change the link structure among these items, use the mapping pane to organize your backlog.
• To create and link tasks to backlog items, use the sprint backlog page; from the web portal you can also drag-and-drop items to change the link structure.
• To indent (), outdent (), and change the link structure of a tree hierarchy, you can re-parent and reorder items from a backlog in the web portal or use a tree query in Team Explorer.

You can also use Excel to change the link structure. See Bulk add or modify work items with Excel.

Test work item links

Test related link types link test case management work items to one another, or to other work items. From the web portal or Microsoft Test Manager, you can view which test cases are defined for a test suite, and which test suites are defined for a test plan. However, these objects aren't linked to each other through link types.

You can link work items to test cases using the Tested/Tested By link types. You use the same link controls you use to link work items to other work items as described earlier.

The following image shows the full set of link types used in linking test management work item types. most links between test management artifacts occur by executing a task from the Test pages or Microsoft Test Manager.

For example, when you add Shared Steps to a Test Case, they are automatically linked using the Test Case/Shared Steps link types. See Share steps between test cases.

From Test you can add test plans, test suites, and test cases—which are linked, but not through a specific link type. Also, the test system creates and manages the associations of test results to test cases and test plans.

Work items linked to code artifacts and build and release pipelines

As you develop your software, you can capture which code changes and builds support the completion of a work item. In this way, your team can understand what work was done or how a bug was fixed through the audit trail of changes to the code base.

The link types used to construct these links—as illustrated in the following image—are: Branch, Build, Changeset, Commit, Found in build, Integrated in build, Pull Request, Versioned Item, and Integrated in release environment.

You can add a link from the work item to the supported artifacts using the method described earlier for linking work items. However, an easier method is to add the work item ID to a commit, pull request, changeset, or other supported Git or TFVC operation at the time you create those items. Also, you can link work items from the Development control within the work item form as described in Work items linked to Git code development.

See the following articles for more information:

• Configure pipelines to support work tracking
• Drive Git development from a work item
• Link and view work items to builds and deployments
• Link to work items from pull requests, commits, and comments
• Auto complete work items with pull requests.

Work items linked to Git code development

The recommended method is to drive development from the work item or add the work item ID when creating branches, commits, and pull requests.

Git lets you link work items to commits by using the Commit link type. You can do this in several ways:

• In Visual Studio Team Explorer, add work item IDs before you commit your changes
  
• You can use the git-commit command and include the work item ID in your comment. For example, you apply this comment #35 Catch null exception to your commit. When you push the commit, the system creates a Commit link between the commit and work item #35.
• And, with the Development control, you can drive your git development from the work item as shown in the following image.

Work items linked to GitHub artifacts

By connecting Azure Boards with GitHub repositories, you enable linking between GitHub commits and pull requests to work items. You can use GitHub for software development while using Azure Boards to plan and track your work.

The link types supported include GitHub Commit, GitHub Issue, and GitHub Pull Request.

Important

You can only link to GitHub artifacts whose repositories you have connected to Azure Boards. To create that connection, see Connect Azure Boards to GitHub. To learn more about linking to GitHub artifacts, see Link GitHub commits, pull requests, and issues to work items.

Work items linked to TFVC code development

Team Foundation version control (TFVC) lets you link work items to version control changesets or versioned source code files by using the Changeset and Versioned Item link types. When you check in pending changes or use My Work to check in changes, work items are automatically linked to your changes.

Work items linked to a Web site, network share, storyboard, or document

You can use the Hyperlinks or Storyboard link type to link a work item to a Web site, network share, or document located on a network share. Both of these link types are one-way links. To add links of this type, you can use the same links controls described earlier for linking work items.

By using the Storyboard link type, you differentiate the link you're adding to specify a storyboard or document that provides work item specifications. Use this link type to provide your team access to the shared file where they can add their comments.

Query for linked work items

To filter items based on hierarchical links, use the Tree of work items query type. To filter items based on all link types, use Work items and direct links.

You can search for work items that not only meet criteria for field values but also that are linked to other work items with specific types of links. This kind of query displays a primary set of work items, which meet the field criteria, and a secondary set, which is linked to items in the primary set.

For query examples, see Link and attachment queries.

Note

You can't construct a query that shows a hierarchical view of Test Plans, Test Suites, and Test Cases. These items aren't linked together using Parent/Child or any other link type. You can only view the hierarchy through the Test>Test Plans page.

Related articles

You should now have a broad understanding of the various link relationships you can create to track dependencies and create an audit trail for your code development.

Once you've formed a link relationship, you can't edit the link type of that relationship from the web portal, but you can do it from Team Explorer.

For more information, see these articles:

• Add link to multiple work items
• Track dependencies using Delivery Plans
• Use mapping to link backlog items to features and epics
• Bulk modify links using Excel
• Link types reference

Visualize related work and other objects

You can view related work items and object within a work item form by installing the Work item visualization extension available from the Visual Studio Marketplace, Azure DevOps tab.