Muokkaa

Jaa


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

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

In this article, learn how to link work items to GitHub commits, pull requests, and branches after connecting your Azure Boards project with a GitHub repository. You can use the #mention syntax for commits and branches or add a GitHub commit, pull request, or branch link directly from the Azure Boards work item.

Note

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

Prerequisites

  • Project connection:

    • Ensure your Azure Boards project is connected to the GitHub repository where the commits, pull requests, and branch you want to link to/from exist. For more information, see Azure Boards-GitHub integration.
  • Permissions:

    • Be a Contributor to both the Azure Boards project and 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. Using AB#ID in a comment doesn't create a link on the work item.

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, and 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 no State is associated with Resolved, the work item transitions to the State associated with the Completed workflow category state. For more information, see How workflow category states are used in Azure Boards backlogs and boards.

Review 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 might 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.

When you add a link to a work item using AB#, those links appear in the Development section of the pull request.

Screenshot of AB# links on the development section of GitHub pull request.

Create GitHub branch from work item

To create a GitHub branch directly from a work item, do these steps:

  1. From your board, find the work item from which you want to create a GitHub branch.

  2. Select Work item actions > New GitHub branch.

    Screenshot of work item More actions select and highlighted New GitHub branch option.

  3. In the Create a GitHub branch dialog, enter the branch name, and select the GitHub repository and base branch.

  4. Select Create.

    Screenshot of Create a GitHub Branch dialog.

    Azure Boards creates the branch in the specified GitHub repository and links it to the work item. For more information, see Azure Boards-GitHub integration.

Note

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

  1. Open the work item and go to the Links tab.

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

  2. From the Add link dialog, select one of the GitHub link types, select a GitHub repository, enter the URL to the GitHub branch, commit, or pull request, and then select Add link.

    In the following example, 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 entered a valid link. The linked-to GitHub repository must be connected to the Azure Boards project or the validation fails.

Note

There's a delay when completing the AB# links if you are using Azure DevOps Server 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 a board

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

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

Next steps