Feedback Edit

Link to work items from other objects

  • Article
  • 7 minutes to read

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

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 or any rich-text field
  • Git commit comments and pull request descriptions
  • TFVC changeset or shelveset comments
  • Wiki pages
  • 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. For more information, 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.

Set work item state in pull request

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.

Screenshot of setting work item state within a PR.

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.

How it works

The system considers the following three different criteria (in this order) when attempting to set the state of #mentioned work items:

  • State
  • State Category
  • keyword

Criteria logic

The following table describes the logic.

Criteria Action
If the value matches a state, Then set it to that state.
Else If the value matches a state category, Then set the work item to first state in that category. See the following note.
Else If the value matches a keyword, Then set the work item to matching keyword state. See the following table.
Else Ignore it and do nothing.

Keyword logic

Keyword logic helps with intent matching. For example, you might enter “Resolves”, but you really meant “Resolved”.

Keyword Action
Proposed, Proposes, Propose Set to the first state in the Proposed category.
InProgress Set to the first state in the In Progress category.
Completed, Completes, Complete Set to the first state in the Completed category.
Resolved, Resolves, Resolve Set to the first state in the Resolved category.
Fixes, Fixed, Fix Close work item. Except Bug, which gets set to Resolved.

Note

Category matching isn't supported on projects using a Hosted XML process. Category matching is only available for projects using an inherited process.

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.

  1. From the Links tab of a work item, choose Add link>Existing item.

  2. 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.

    Add link dialog with Build link type selected.

  3. 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.

    Find builds dialog with project selected and builds listed.

  4. Choose the build from the list you want to link to and then choose OK.

  5. From the Add link dialog, choose OK to complete the operation.

    Add link dialog with Build number filled in.

You can link work items to existing builds from the Add link dialog.

  1. From the Links tab of a work item, choose Add link>Existing item.

  2. 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.

    Add link dialog with Build link type selected.

  3. 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.

    Find builds dialog, link to a build within your project.

  4. Choose the build from the list you want to link to and then choose OK.

  5. From the Add link dialog, choose OK to complete the operation.

    Add link dialog with Build number filled in.

Link to work items from a Wiki page

Enter # to trigger the #ID work item picker from within a Wiki page.

For more information about the built-in wiki, see Add & edit wiki pages and Wiki Markdown guidance.

You can also you link a query results table to a wiki. This supports quick access to each linked work item in the query. For more information, see Wiki Markdown guidance.

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