Link work items and other objects
Azure DevOps Services | Azure DevOps Server 2022 - Azure DevOps Server 2019 | TFS 2018
You can link work items to other work items to manage dependencies and see relationships within your work. These work items can be within the same project or in different projects in your organization. You can also link work items to other objects such as versioned items, or network resources, and external (Git) builds and commits.
You can link work items to other work items to manage dependencies and see relationships within your work. These work items can be within the same project or in different projects in your collection. You can also link work items to other objects such as versioned items, or network resources, and external (Git) builds and commits.
Prerequisites
Backlogs automatically get 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 be added to a project as a member of the Contributors or Project Administrators security group.
- To add or modify work items, you must be granted Stakeholder access or higher.
- 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 Allow. For more information, see Set permissions and access for work tracking.
- To use the Planning pane, your team administrator must define iteration (sprint) paths and configure team iterations.
Note
Users with Stakeholder access for public projects have full access to backlog and board features, like users with Basic access. For more information, see Stakeholder access quick reference.
- You must be added to a project as a member of the Contributors or Project Administrators security group.
- To add or modify work items, you must be granted Stakeholder access or higher.
- 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 Allow. For more information, see Set permissions and access for work tracking.
- To use the Planning pane, your team administrator must define iteration (sprint) paths and configure team iterations.
Link several work items
From the web portal, open a backlog or 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, choose Add link, and then choose Existing item... or New item....
In the following example, we multi-select from the product backlog and choose Existing item....
Link to an existing work item
From the Add link dialog, choose from the following link types. For more information, see Link type reference.
- Duplicate: When two work items capture the same information; close one of the work items and keep the other one active.
- Parent/Child: When you want to break down work items into smaller items--for example, break down features into stories, or stories into tasks.
- Predecessor-Successor: When you want to track tasks that must be completed before you can start others.
- Related: 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.
Tip
Don't nest 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. For example, drag-and-drop of work items on a backlog or display of items on a Kanban board may not work. For more information, see Fix display, reordering, and nesting issues.
From the Add link dialog, select the link type, enter a work item ID, and then choose OK.
In the following example, we use the Related link type to link three items to the bug with ID of 400.
You can only add links one at a time. (You can no longer enter their IDs separated by commas or spaces.) To quickly find work items of interest, use work item search.
- To view the work items selected for linking, you can choose the
.
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 
More actions.
- If you're working from the Query Results page, bulk save the work items you've modified. When you work from a backlog, work items automatically save.
Change the link type of an existing link
Note
The Edit link feature requires you to enable the New Boards Hub preview feature.
Open your work item and select Links.
Select
More actions > Edit link.
Choose the link type to change to, and then select Save.
Save the work item.
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 you selected opens. Enter additional information and Save the work item.
If you're working from the Query Results page, bulk save the work items you've modified.
Link to a remote work item
You can link work items to objects defined in other Azure DevOps organizations as long as both organizations use the same Azure Active Directory to manage users.
Choose from one of the following two remote link types supported.
- Consumes From/Produces For: When you want to track dependencies of work items that are defined in different organizations and managed by different teams.
- Remote Related: When the work items being linked are defined in different organizations and managed by different teams, but don't have strong inter-dependencies.
From the Add link dialog, select the link type, enter the URL of the remote work item, and then choose OK.
In the following example, we use the Remote Related link type to link to work item ID 350 that exists in the remotelinkingtest2 organization, RemoteLinking project.
The link tab maintains a count of all links to the work item. The Remote Link Count field maintains a count of the number of links added to a work item that link to a work item defined in another project or organization.
The following example shows two remote links, indicated by the 
cloud icon, added to a user story.
Link several work items to a new git branch
You can add a new git branch and link them to existing work items at the same time.
From a backlog or query results page, multi-select the work items you want to link to a new git branch, choose the 
actions icon, and then New branch.... For more information, see Link work items to Git development objects.
Link work items to a build in same or other projects
You can link work items to existing builds from the Add link dialog. These builds can be within your project or to other projects in your organization or collection.
Note
This feature requires installation of Azure DevOps Server 2020.1 update. To learn more, see Azure DevOps Server 2020 Update 1 RC1 Release Notes, Boards.
From the Links tab of a work item, choose Add link>Existing item.
From the Add link dialog, choose one of the build link types—Build, Found in build, Integrated in build— and specify the build number.
If you don't know the build number—a combination of the pipeline and build name—you can search for it by choosing the
icon.
From the Link builds dialog, choose the parameters to filter your search of builds.
If linking to a build in a different project, then first choose the Project whose build you want to link to.
For example, you can specify a build number, select a build pipeline, a build result—such as, All, succeeded, partially succeeded, failed, or canceled. Or, with All selected for Result, choose Find to list the available builds to link to.
Choose the build from the list you want to link to and then choose OK.
From the Add link dialog, choose OK to complete the operation.
Link work items to a build
You can link work items to existing builds from the Add link dialog.
From the Links tab of a work item, choose Add link>Existing item.
From the Add link dialog, choose one of the build link types—Build, Found in build, Integrated in build— and specify the build number.
If you don't know the build number—a combination of the pipeline and build name—you can search for it by choosing the
icon.
From the Link builds dialog, choose the parameters to filter your search of builds.
For example, you can specify a build number, select a build pipeline, a build result—such as, All, succeeded, partially succeeded, failed, or canceled. Or, with All selected for Result, choose Find to list the available builds to link to.
Choose the build from the list you want to link to and then choose OK.
From the Add link dialog, choose OK to complete the operation.
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 in another project, then first open that project. Then, make your selections:
- Query: When you've defined a query that you know contains the set or superset of the work items that you want.
- IDs: 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: 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.
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: Hold down the shift key to select several items in a sequence. Use the Ctrl key to select several non-sequential items.
From 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.
Link work items to pull requests
In the description of your pull request, enter
#to trigger the#IDwork item picker. You see a list of 50 work items that you've recently modified or are assigned to you.
Enter up to five keywords that match the work item type, ID, or title to narrow the list of suggested work items.
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.
When you create a pull request, you can set the state value of the linked work items in the description. Follow the syntax: {state value}: #ID.
When you merge the pull request, the system reads the description and updates the work item state. In the following example, we set work items #300 and #301 to Resolved, and #323 and #324 to Closed.
Note
This feature requires installation of Azure DevOps Server 2020.1 update. To learn more, see Azure DevOps Server 2020 Update 1 RC1 Release Notes, Boards.
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.
Use Azure CLI to add, remove, and show links
You can add, remove, and show details of links made to a work item using link types supported by your organization with the az boards work-item relation command. For more information, see Get started with Azure DevOps CLI.
Link types include work link types, remote link types, hyperlinks, and attached files. For a list of all link types that you can specify, run the az boards work-item relation list-type command.
az boards work-item relation add
az boards work-item relation remove
az boards work-item relation show
In the following examples, the organization is fabrikam and the project ID corresponds to cebd7ef5-4282-448b-9701-88c8637581b7. The table format is used to show the output. For other formats, see Output formats for Azure CLI commands.
Link work items
To link one or more work item to a single work item, enter the az boards work-item relation add command.
Syntax
Required parameters include the ID of the work item to link to and the link type. Supported link types include Parent, Child, Related, Remote Related. For a list of all link types that you can specify, run the az boards work-item relation list-type command.
For work items defined within the same organization, you must specify the work item ID or target URL. For work items defined in a remote organization, you must specify the target URL. You can specify multiple values by separating IDs or URLs with a comma.
az boards work-item relation add --id
--relation-type
[--detect {false, true}]
[--org]
[--target-id]
[--target-url]
Example
The following command links work item ID=2807 to work item ID=2794 with the Child link type. The command returns a list of all links currently defined for the work item.
az boards work-item relation add --id 2794 --relation-type Child --target-id 2856 --output table
Are you sure you want to remove this relation(s)? (y/n): y
Relation Type Url
--------------- -------------------------------------------------------------------------------------------------
Child https://dev.azure.com/fabrikam/cebd7ef5-4282-448b-9701-88c8637581b7/_apis/wit/workItems/2850
Child https://dev.azure.com/fabrikam/cebd7ef5-4282-448b-9701-88c8637581b7/_apis/wit/workItems/2808
Child https://dev.azure.com/fabrikam/cebd7ef5-4282-448b-9701-88c8637581b7/_apis/wit/workItems/2820
Child https://dev.azure.com/fabrikam/cebd7ef5-4282-448b-9701-88c8637581b7/_apis/wit/workItems/2856
Parent https://dev.azure.com/fabrikam/cebd7ef5-4282-448b-9701-88c8637581b7/_apis/wit/workItems/2811
Child https://dev.azure.com/fabrikam/cebd7ef5-4282-448b-9701-88c8637581b7/_apis/wit/workItems/2876
Child https://dev.azure.com/fabrikam/cebd7ef5-4282-448b-9701-88c8637581b7/_apis/wit/workItems/2801
Child https://dev.azure.com/fabrikam/cebd7ef5-4282-448b-9701-88c8637581b7/_apis/wit/workItems/2877
Child https://dev.azure.com/fabrikam/cebd7ef5-4282-448b-9701-88c8637581b7/_apis/wit/workItems/2805
Child https://dev.azure.com/fabrikam/cebd7ef5-4282-448b-9701-88c8637581b7/_apis/wit/workItems/2807
To view the information for the linked work items, enter one of the URLs listed in your browser.
Remove work item links
To remove one or more linked work items from a single work item, enter the az boards work-item relation remove command.
Required parameters include the ID of the work item to remove the link from and the link type. You can only remove links to work items defined in the same organization. You can specify any of the supported link types except remote link types.
You must specify the target work item ID. You can specify multiple values by separating IDs or URLs with a comma.
Syntax
az boards work-item relation remove --id
--relation-type
--target-id
[--detect {false, true}]
[--org]
[--yes]
Example
The following command removes the link to work item ID=2794 from work item ID=2856 to work item with the Child link type. The command returns a list of all links currently defined for the work item.
az boards work-item relation remove --id 2794 --relation-type Child --target-id 2807 --output table
Are you sure you want to remove this relation(s)? (y/n): y
Relation Type Url
--------------- -------------------------------------------------------------------------------------------------
Child https://dev.azure.com/fabrikam/cebd7ef5-4282-448b-9701-88c8637581b7/_apis/wit/workItems/2850
Child https://dev.azure.com/fabrikam/cebd7ef5-4282-448b-9701-88c8637581b7/_apis/wit/workItems/2808
Child https://dev.azure.com/fabrikam/cebd7ef5-4282-448b-9701-88c8637581b7/_apis/wit/workItems/2820
Child https://dev.azure.com/fabrikam/cebd7ef5-4282-448b-9701-88c8637581b7/_apis/wit/workItems/2856
Parent https://dev.azure.com/fabrikam/cebd7ef5-4282-448b-9701-88c8637581b7/_apis/wit/workItems/2811
Child https://dev.azure.com/fabrikam/cebd7ef5-4282-448b-9701-88c8637581b7/_apis/wit/workItems/2876
Child https://dev.azure.com/fabrikam/cebd7ef5-4282-448b-9701-88c8637581b7/_apis/wit/workItems/2801
Child https://dev.azure.com/fabrikam/cebd7ef5-4282-448b-9701-88c8637581b7/_apis/wit/workItems/2877
Child https://dev.azure.com/fabrikam/cebd7ef5-4282-448b-9701-88c8637581b7/_apis/wit/workItems/2805
To view the information for the linked work items, enter one of the URLs listed in your browser.
Show details of links made for a single work item
To view the work items linked to a single work item, enter the az boards work-item relation show command. For a list of all link types that can be returned, run the az boards work-item relation list-type command.
Syntax
az boards work-item relation show --id
[--detect {false, true}]
[--org]
Example
The following command lists the details of links defined for work item ID=2931 in the fabrikam organization in table format.
az boards work-item relation show --id 2931 --output table
Relation Type Url
--------------- -----------------------------------------------------------------------------------------------------------------------------------
Related https://dev.azure.com/fabrikam/cebd7ef5-4282-448b-9701-88c8637581b7/_apis/wit/workItems/2932
Successor https://dev.azure.com/fabrikam/cebd7ef5-4282-448b-9701-88c8637581b7/_apis/wit/workItems/2932
Remote Related https://dev.azure.com/fabrikam-fiber5/847568d2-6541-4a99-a240-228510ccbff7/_apis/wit/workItems/1777
Parent https://dev.azure.com/fabrikam/cebd7ef5-4282-448b-9701-88c8637581b7/_apis/wit/workItems/2930
Predecessor https://dev.azure.com/fabrikam/cebd7ef5-4282-448b-9701-88c8637581b7/_apis/wit/workItems/2933
Attached File https://dev.azure.com/fabrikam/cebd7ef5-4282-448b-9701-88c8637581b7/_apis/wit/attachments/1cc6c026-b4ed-420c-bfe6-065be726cba7
To view the information for the linked work items, enter one of the URLs listed in your browser. Choose the URL for an attached file to download the attachment.
Related articles
Feedback
Submit and view feedback for