Edit

Link GitHub commits, pull requests, and issues to work items in Azure Boards

  • Article

Azure DevOps Services | Azure DevOps Server 2022 - Azure DevOps Server 2019

Once you connect your Azure Boards project with a GitHub repository, you can link work items to your GitHub commits and pull requests. You can add links using the #mention syntax familiar to GitHub users or you can add a GitHub commit or GitHub pull request link type from the Azure Boards work item.

Note

With the Azure Boards app for GitHub, Azure Boards and Azure DevOps Services support integration with GitHub.com and GitHub Enterprise Server repositories. Azure DevOps Servers 2019 and later versions support integration with GitHub Enterprise Server repositories only.Integration with other Git repositories is not supported.

Prerequisites

  • Your Azure Boards project must be connected to the GitHub repository where the commits and pull requests you want to link to/from exist. For more information, see Azure Boards-GitHub integration.
  • You must be a Contributor to Azure Boards project and to the GitHub repository.

Note

Projects that use the Hosted XML process model require updates to the work item types to view the Development section and GitHub link types. For more information, see Update XML definitions for select work item types.

From a GitHub commit, pull request or issue, use the following syntax to create a link to your Azure Boards work item. Enter the AB#ID within the text of a commit message. Or, for a pull request or issue, enter the AB#ID within the title or description (not a comment).

Note

Linking to GitHub issues requires Azure DevOps Server 2019 Update 1 or later version.

AB#{ID}

For example, AB#125 links to work item ID 125.

You can also enter a commit or pull request message to transition the work item. The system recognizes fix, fixes, fixed and applies it to the #-mention item that follows. Mentioned work items transition to the first State associated with the Resolved workflow category state. If there's no State associated with Resolved, then it transitions to the State associated with the Completed workflow category state. To understand how workflow states and category states are mapped, see How workflow category states are used in Azure Boards backlogs and boards.

See the following table of examples.

Commit or pull request message Action
Fixed AB#123 Links and transitions the work item to the Resolved workflow state category or, if none is defined, then the Completed workflow state category.
Adds a new feature, fixes AB#123. Links and transitions the work item to the Resolved workflow state category or, if none is defined, then the Completed workflow state category.
Fixes AB#123, AB#124, and AB#126 Links to Azure Boards work items 123, 124, and 126. Transitions only the first item, 123 to the Resolved workflow state category or, if none is defined, then the Completed workflow state category.
Fixes AB#123, Fixes AB#124, Fixes AB#125 Links to Azure Boards work items 123, 124, and 126. Transitions all items to either the Resolved workflow state category or, if none is defined, then the Completed workflow state category.
Fixing multiple bugs: issue #123 and user story AB#234 Links to GitHub issue 123 and Azure Boards work item 234. No transitions are made.

Note

If you connected the same GitHub repo to projects defined in two or more Azure DevOps organizations, you may see unexpected AB# mention linking. For more information, see Resolve connection issues. For this reason, we recommend that you only connect a GitHub repo to projects defined in a single Azure DevOps organization.

Note

Linking to a GitHub issue requires Azure DevOps Server 2019 Update 1 or later version.

  1. To link to a commit or pull request, open the work item and choose Add link under the Development section.

    Screenshot of work item form, Development section, Add link option.

    To link to an issue, choose the Links tab, and then choose Add Link>Existing item.

    Screenshot of work item form, Links tab, Add link to issue.

  2. From the Add link dialog, select one of the GitHub link types, enter the URL to the commit, pull request, or issue and then choose OK.
    Here, we add a link to a GitHub pull request.

    Screenshot of work item form, Links tab, Add link dialog, GitHub pull request link type selected.

    Azure Boards completes a check to ensure that you've entered a valid link. The linked-to GitHub repository must be connected to the Azure Boards project or the validation fails.

    Here, we add a link to a GitHub issue.

    Screenshot of work item form, Links tab, Add link dialog, GitHub issue link type selected.

Note

There is a delay when completing the AB# links if you are using Azure DevOps Sever and GitHub Enterprise Server. We have a 'push-and-pull' design to pull from the GitHub events every hour on the incremental changes on Commit, PR, and Issue.

The Development section within the work item form lists the links created to GitHub commits and pull requests with the GitHub icon.

Screenshot of work item form, Development section shows GitHub links.

Choose the link provided to open the commit or pull request in GitHub.

View GitHub objects on Kanban board

With GitHub annotations enabled on the Kanban board, you can quickly open linked GitHub commits, pull requests, or issues for more detail. For more information, see Customize cards.

Screenshot of Kanban board that shows GitHub links on work item cards.

Note

GitHub annotations requires Azure DevOps Server 2019 Update 1 or later version.

Next steps

Configure status badges