Link to work items from other objects

  • Article

TFS 2017 | TFS 2015

By linking to work items from other objects, such as builds, commits, pull requests, and more, you support your team's ability to maintain an audit trail of related work. All users can add links to their work items.

You can enter #ID from within the following areas to link to your work items:

  • A work item discussion
  • Git commit comments and pull request descriptions
  • TFVC changeset or shelveset comments

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:

The link types used to link work items to devops objects—as illustrated in the following image—are Build, Found in build, Integrated in build, Integrated in release for build and release pipelines; Branch, Commit, Pull Request, and Tag for Git repositories, and Changeset, Shelveset and VersionedItem for Team Foundation Version Control (TFVC) repositories. These are all designated as external link types.

Conceptual image of link types used to link work items to devops objects.

From the work item form, Links tab, you can view all the objects linked to the work item as described later in this article. However, you can't create a work item query to list those links. Work item queries only return work items that are linked to other work items. However, you can create a query that lists work items that contain external links. To learn how, see Query by link or attachment count.

Note

You can also link to work items from GitHub commits, pull requests, and issues. This requires connecting your Azure DevOps project to your GitHub repository. To learn more, see Azure Boards-GitHub integration.

  1. Enter # to trigger the #ID work item picker in your pull request commits, commit comments, changeset comments, shelveset comments, description, and more. You see a list of 50 work items that you've recently modified or that are assigned to you.

    Screenshot of work item list produced when entering # in PR description.

  2. Narrow the list of suggested work items by entering keywords that match the work item type, ID, or title.

    Screenshot of entering keyword after # and resulting work item in search

    To further filter the list, continue to enter keywords until you find a match. You can enter up to five keywords.

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.

Screenshot of Links tab with count of 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.

Screenshot of Links tab with many linked objects.

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.

Azure Repos, Git