Link user stories, issues, bugs, and other work items in Azure Boards
Azure DevOps Services | Azure DevOps Server 2020 | Azure DevOps Server 2019 | TFS 2018 - TFS 2013
Link work items to other work items to manage dependencies and see relationships within work. You can link work items within your project or to work items within another project in your collection. Use different link types to support different business goals. You can also link work items to other objects such as builds, commits, versioned items, or network resources.
In general, you use the following link types when linking work items to one another:
- Use Parent/Child links to link work items that you want to group within a hierarchy
- Use Predecessor/Successor or Affects/Affected by links to link work items that have dependencies
- Use Duplicate/Duplicate of links to link work items that track the same code defect or work
- Use Related to link work items with some level of relationship, but not that strong
You can add a link to a work item from within the work item form or from a backlog or query results list. From a backlog or query results list, you can select multiple work items and then link them to a new or existing work item. In general, use the bulk edit to update several work items to link to the same work item, either new or existing.
Use this article to learn how to:
- Link one or more work items to an existing work item
- Link one or more work items to a new work item that you add when linking
- Link several work items to a new git branch
- Link work items to a build artifact
- Find work items that you want to link to
- Bulk modify link relationships
Note
If you want to link work items in a parent-child hierarchy, use the mapping pane as described in Organize your backlog and map child work items to parents. If you want to link test cases to user stories, see Add, run, and update inline tests and Create test plans and test suites.
For an overview of how links are used to support traceability, see End-to-end traceability.
Link guidance
For an overview of which link types to use and link-related capabilities, see Linking, traceability, and managing dependencies. In general, we recommend you follow these guidelines:
- For work items that appear on your backlogs, both product and portfolio, use the Parent and Child link types to create a hierarchy and group work. To quickly link many backlog work items within a hierarchy, see Organize your backlog, map child work items to parents.
- When linking work items with Parent and Child link types, avoid nesting work items of the same type. While the system allows you to nest work items of the same type, such as linking bugs to bugs or bugs to user stories when tracking both types on your product backlog, it can cause problems with drag-and-drop of work items on a backlog or display of items on a Kanban board. To learn more, see Fix display, reordering, and nesting issues.
- To track dependencies of work items, use the Predecessor and Successor link types.
- For all other general tracking purposes, use the Related link type.
The following link relationships are restricted:
- You can't assign a work item more than one parent using a Parent/Child or other tree-topology link type. To learn more about link types, see Link type reference.
- You can't add links in such a way as to create a circular relationship.
- You can't link more than 1,000 work items to a single work item.
Prerequisites
Backlogs are automatically created when you create a project or add a team. Each team has access to their own product, portfolio, and sprint backlogs as described in About teams and Agile tools.
- You must connect to a project. If you don't have a project yet, create one.
- You must be added to a project as a member of the Contributors or Project Administrators security group. To get added, Add users to a project or team.
- To add or modify work items, you must be granted Stakeholder access or higher. For details, see Stakeholder access quick reference.
- To view or modify work items, you must have your View work items in this node and Edit work items in this node permissions set to Allow. By default, the Contributors group has this permission set. To learn more, see Set permissions and access for work tracking.
Link several work items
From the web portal, open a query results page, and multi-select the work items you want to add a link to.
Open the context menu of one of the selected work items, and then choose Link selected item(s) to a new work item... or Link to an existing item....
Here we multi-select from the Queries page and choose Link selected item(s) to a new work item....
Link to an existing work item
When you link work items, you select a link type. In general, use the following link types as indicated. To learn more about each link type, see Link type reference.
- 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.
From the Add link dialog, select the link type, enter a work item ID, and then choose OK.
For example, here we use the Related link type to link three items to the bug with ID of 400.
To link to multiple work items, enter their IDs separated by commas or spaces. If you don't know the IDs or you want to link to an item in a different project, you can choose the … context menu to open a dialogue that will support you in choosing work items that are based on IDs, a query, or title keyword.
If you're working from the Query Results page, you'll need to bulk save the work items you've modified. When you work from a backlog, work items are automatically saved.
Link to a new work item
Here, we've selected to add a link to the selected work items.
Specify the link type, work item type, and title of the new work item. Choose OK.
A work item of the type selected opens. Enter additional information and save the work item.
If you're working from the Query Results page, you'll need to bulk save the work items you've modified as shown in the previous procedure.
Find work items to link to
From the Add link dialog, you can open a secondary dialog to help you choose one or more work items to link to. If you're going to find and list work items to link to by using a saved query, first define the query that you want to use.
From the Add link dialog, choose the … context menu or Browse button (Visual Studio) to open the following dialog.
If the work items are defined in another project, then first select the Project. Then, make your selections:
Query. Use this method when you've defined a query that you know contains the set or superset of the work items that you want.
IDs. Use this method when you know the IDs of the work items that you want to link to. In the IDs box, type the IDs of the work items that you want to find, separated by commas or spaces.
Title contains. Use this method to find work items that have a common word or phrase in the title field. In the and type list, select the type of work item that you want to retrieve.
Note
To minimize the time required to run the query, narrow the filter criteria of the search.
Select the Find button.
Only those work items defined for the selected project and specified work item type are listed. To sort on a column field, choose the column title.
In the list of returned work items, select one or more work items.
From the web portal: To select several items in a sequence, hold down the shift key. To select several non-sequential items, use the Ctrl key.
For Visual Studio, select each work item that should link to the current work item. You can also press the SHIFT key while clicking to select a range of work items, or press the CTRL key while clicking to select multiple work items.
More options for modifying links in bulk
Other features you can use to quickly link or change links that use the parent-child link type (some features are version-dependent, see the linked article for details):
- To quickly link backlog items to portfolio backlog items with parent-child links, use the mapping pane to organize your backlog. Or, you can choose to Show Parents and drag-and-drop items within the tree hierarchy.
- To create and link tasks to backlog items, use the sprint backlog page.
- To indent (
), outdent (
), and change the tree hierarchy, use a tree query in Visual Studio. - To add or delete work items or change the link structure, you can use Excel. See Bulk add or modify work items with Excel.
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.