Link GitHub commits, pull requests, and issues to work items

Azure Boards | Azure DevOps Server 2019

When using GitHub with Azure Boards, it's easy to keep all of your work connected. Links can be added using the #mention syntax familiar to GitHub users or from the Azure Boards work item.

Note

Azure Boards and Azure DevOps Services support integration with GitHub.com and GitHub Enterprise Server repositories.

Azure DevOps Server 2019 supports integration with GitHub Enterprise Server repositories.

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 details, see Connect Azure Boards to GitHub.
  • You must be a Contributor to Azure Boards.
  • You must be a Contributor to the GitHub repository.
  • If your organization uses the Hosted XML process model to customize the work tracking experience, you'll need to update the work item types to link to and view the GitHub link types from the Development section in the work item form. For details, 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).

From a GitHub commit or pull request, 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, enter the AB#ID within the pull request title or description (not a pull request comment).

AB#{ID}

For example, AB#125 will link to work item ID 125.

In addition, you can enter a commit or pull request message to transition the work item. The system will recognize fix, fixes, fixed and apply it to the #-mention item that follows. Some examples are provided as shown.

Examples:

Commit message Action
Fixed AB#123 Links and transitions the work item to the "done" state.
Adds a new feature, fixes AB#123. Links and transitions the work item to the "done" state.
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 "done" state.
Fixes AB#123, Fixes AB#124, Fixes AB#125 Links to Azure Boards work items 123, 124, and 126. Transitions all items to the "done" state.
Fixing multiple bugs: issue #123 and user story AB#234 Links to GitHub issue 123 and Azure Boards work item 234. No transitions.

Note

If you have connected the same GitHub repo to projects defined in two or more Azure DevOps organizations, you may see unexpected AB# mention linking. For details, see Troubleshoot GitHub & Azure Boards integration. 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.

    Development section, Add link

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

    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.

    GitHub pull request link dialog

    Azure Boards performs a check to ensure that you've entered a valid link. The linked-to GitHub repository must be integrated with the project or the validation will fail.

    Here, we add a link to a GitHub issue.

    Add link dialog, GitHub issue

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

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.

Kanban board shows GitHub links

Note

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

For details on enabling annotations, see Customize cards.

Try this next