Skip to content

Latest commit

 

History

History
190 lines (124 loc) · 9.79 KB

add-links-to-work-items.md

File metadata and controls

190 lines (124 loc) · 9.79 KB
title titleSuffix description ms.technology toc ms.custom ms.author author ms.topic monikerRange ms.date
Link work items to other objects
Azure DevOps
Learn how to link work items to builds, commits, pull requests, and more.
devops-collab
show
contperf-fy21q2
chcomley
chcomley
conceptual
>= tfs-2015
04/16/2021

Link to work items from other objects

[!INCLUDE temp]

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:

::: moniker range=">= azure-devops-2020"

  • A work item discussion or any rich-text field
  • Git commit comments and pull request descriptions
  • TFVC changeset or shelveset comments
  • Wiki pages ::: moniker-end

::: moniker range="<= azure-devops-2019"

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

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:

Supported link types to devops objects

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.

:::image type="content" source="media/add-link/conceptual-link-types-devops-objects.png" alt-text="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.

::: moniker range="tfs-2015"

Note

The #ID feature is available from TFS 2015 Update 1 and later versions.

::: moniker-end

Link to work items from pull requests, commits, and comments

  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.

    :::image type="content" source="media/link-pr-to-work-item.png" alt-text="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.

    :::image type="content" source="media/keyword-pr-link.png" alt-text="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.

::: moniker range="tfs-2015"

Note

Requires TFS 2015 Update 2 or a later version. ::: moniker-end

::: moniker range=">= azure-devops-2020"

Set work item state in pull request

::: moniker-end

[!INCLUDE temp]

::: moniker range=">= azure-devops-2020"

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.

::: moniker-end

[!INCLUDE temp]

::: moniker range=">= tfs-2018"

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. ::: moniker-end

::: moniker range=">= azure-devops-2019" 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. ::: moniker-end

[!INCLUDE temp]

Related articles

::: moniker range=">= azure-devops-2020"

::: moniker range="< azure-devops-2020"

Azure Repos, Git