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

Azure DevOps Services | Azure DevOps Server | Azure DevOps Server 2022

In this article, learn how to link work items to GitHub commits, pull requests, branches, and builds after you connect your Azure Boards project to a GitHub repository. Use #mention syntax for commits and branches, use ! mentions to reference GitHub pull requests in work item discussions, or add a GitHub commit, pull request, or branch link directly from the Azure Boards work item.

Prerequisites

Use AB# to link from GitHub to Azure Boards work items

Use AB# mentions in GitHub text to link to Azure Boards work items.

To create a link:

1. Add AB#{ID} to a commit message, pull request description, or issue description.
2. Push the commit or save the pull request or issue.
3. Open the work item to confirm the link appears in the Development section.

Using AB#ID in a comment or in a pull request title doesn't create a link on the work item.

AB#{ID}

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

You can also transition work items from commit or pull request text. Azure Boards recognizes {state} or {state category} and keywords such as fix, fixes, and fixed, and then applies that transition to the AB# reference that follows.

When a pull request description includes a valid state name, for example, Closed AB#1234, the system updates the referenced work item to that specific state. If the state name isn't recognized directly, Azure Boards tries to match it to a workflow category like Resolved or Completed. If a match is found, the work item transitions to the first available state defined under that category.

By default, work items referenced with fix, fixes, or fixed transition to the first state associated with the Resolved category. If no such state exists in the current process, the system instead transitions the work item to the first state in the Completed category.

For more information, see How workflow category states are used in Azure Boards backlogs and boards.

Use the following link-only examples:

Use the following link-and-transition examples:

When you add a link to a work item using AB# in a pull request description, those links appear in the Development section of the GitHub pull request. These links are available only when you use AB# in the pull request description. They don't appear if you link to the pull request directly from the work item. Removing the AB# reference from the description also removes it from the Development section.

Create GitHub branch from work item

To create a GitHub branch directly from a work item, use the following steps:

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

2. Select Work item actions > New GitHub branch.

   

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

4. 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

1. Open your work item and go to the Development area.

2. Select Add link. From each dropdown menu, select your link type, GitHub repository, and GitHub pull request. You can search and drill down within the repository to find and select a specific pull request or commit, without needing to copy and paste a URL.

3. Select Add link.

   

   Azure Boards checks 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.

Automatic link updates

Several events automatically update the links on the work item form, so you don't need to create them manually. These events include:

View or open links from the Development section

The Development section in the work item form lists the links created to GitHub commits and pull requests by using the GitHub icon.

Select the link to open the commit or pull request in GitHub.

GitHub pull request insights

Linked GitHub pull requests in the Development section show extra status details. You can assess progress without opening the pull request in GitHub.

Prerequisites for pull request insights

To see pull request insights, go to the Azure Boards app in GitHub and accept the updated permissions for read and write access to Checks.

View pull request status details

1. Open a work item that has a linked GitHub pull request.

2. In the Development section, find the linked pull request. The following status details appear next to the pull request link:

   • Draft status: Shows whether the pull request is still a draft.
   • Review status: Shows whether the pull request needs review, is approved, or has changes requested.
   • Checks status: Shows whether CI checks are passing, failing, or pending.

   

3. Hover over a status indicator to see more details, or select the pull request link to open it directly in GitHub.

Mention GitHub pull requests by using !

Use ! mentions to reference and discuss GitHub pull requests directly from any work item rich-text field or discussion comment. When you type ! in a text field, a picker appears that you can use to search for and select a GitHub pull request from a connected repository. The selected pull request is inserted as a clickable link.

This feature makes it easy to reference related pull requests in work item descriptions, acceptance criteria, or discussion threads without manually copying URLs.

View build status for YAML pipelines (Integrated in build)

When you use Azure Pipelines YAML to build code hosted in a GitHub repository, you can automatically create Integrated in build links on associated work items. This feature provides build traceability for GitHub repos, achieving parity with the experience available for Azure Repos.

To enable this feature:

1. Open your YAML pipeline, select More actions, and then select Settings.

2. In the Pipeline settings dialog, enable Automatically link new work items in this build.

   

When the build finishes, an Integrated in build link automatically appears in the Development section of each associated work item, giving your team full traceability from work item to build.

For more information about configuring this setting, see Configure pipelines to support work tracking.

View GitHub objects on a board

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

Use AI to link and manage GitHub work

If you configure the Azure DevOps MCP Server, you can describe GitHub-to-work-item linking tasks in natural language instead of navigating the work item form manually.

Use these prompts as scenario examples. Supported operations vary by configured toolsets, extension version, and your permissions.

Some prompts might return guidance instead of performing a write action, or they might require multiple prompts depending on the MCP tools you enabled.

Before you run a prompt, replace placeholders such as <Contoso>, <owner/repo>, and <sha> with your actual values.

Use this quick run-and-verify flow:

1. Run one prompt from the table.
2. Review the response for the action taken.
3. Open the work item and confirm the result in the Development section.
4. Open the related GitHub artifact and confirm the expected link or update.

Try these prompts first:

• Link work item AB#125 in project <Contoso> to GitHub pull request <owner/repo>#42
• Link work item AB#312 in project <Contoso> to GitHub commit <owner/repo>@<sha>
• Summarize all GitHub commits and pull requests linked to work item AB#312 in project <Contoso>

Troubleshoot AI-assisted linking

• If a prompt doesn't run, confirm that agent mode is enabled in your AI client.
• If a prompt fails with access errors, verify that your account has access to the Azure DevOps project and GitHub repository.
• If links aren't created, replace all placeholders (for example, <Contoso>, <owner/repo>, <sha>) with real values and run the prompt again.
• If a bulk prompt fails, retry with a single work item first, then repeat with a smaller batch.
• If results still don't match expectations, verify the outcome in the work item Development section and in the related GitHub artifact.

Next step

Related content

• Integrate Azure Boards with GitHub
• Configure pipelines to support work tracking
• Understand how workflow category states are used in Azure Boards backlogs and boards
• Link work items to objects
• Resolve GitHub and Azure Boards connection issues