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.
Use AB# to link from GitHub to Azure Boards work items
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.
Create GitHub branch from work item
To create a GitHub branch directly from a work item, do these steps:
From your board, find the work item from which you want to create a GitHub branch.
Select
Work item actions > New GitHub branch.
In the Create a GitHub branch dialog, enter the branch name, and select the GitHub repository and base branch.
Select Create.
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.
Add work item link to GitHub branch, commit, or pull request
Note
Linking to a GitHub issue requires Azure DevOps Server 2019 Update 1 or later version.
Open the work item and go to the Links tab.
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.
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.
View or open links from the Development section
The Development section within the work item form lists the links created to GitHub commits and pull requests with the 
GitHub icon.
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.
