Edit

Azure Boards-GitHub integration

  • Article

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

Use this guide to connect Azure Boards with one or more GitHub repositories. This connection uses the Azure Boards app for GitHub to support the integration between Azure Boards and GitHub. This app is free for both public and private repositories.

By connecting Azure Boards with GitHub repositories, you enable linking between GitHub commits, pull requests, and issues to work items. You can use GitHub for software development while using Azure Boards to plan and track your work. Azure Boards provides the scalability to grow as your organization and business needs grow.


Note

Azure DevOps only supports integation with GitHub repositories or Azure Repos Git repositories. Integration with other Git repositories is not supported.

Sign up for Azure Boards

If you haven't yet signed up for Azure Boards, you can do that now. See Sign up for free and invite others to collaborate on your project. You can also sign up and sign in using your GitHub credentials.

GitHub signin

Along with accessing developer services such as Azure DevOps and Azure, you can use your GitHub account to access all Microsoft online services, from Excel Online to XBox.

Supported integration scenarios

Azure Boards and Azure DevOps Services support integration with GitHub.com and GitHub Enterprise Server repositories. On-premises Azure DevOps Servers support integration with GitHub Enterprise Server repositories.

Note

By installing the Azure DevOps Server 2020.1.1 Patch 2, you can create connections from your Azure DevOps Server to GitHub.com repositories in addition to GitHub Enterprise Server repositories.

Azure Boards-GitHub integration supports the following connections:

  • From GitHub:

    • Support integration for all repositories for a GitHub account or organization, or select repositories.
    • Add or remove GitHub repositories that participate in the integration and configure the project they connect to.
    • Suspend Azure Boards-GitHub integration or uninstall the app.

  • From Azure Boards:

    • Connect one or more GitHub repositories to an Azure Boards project.
    • Add or remove GitHub repositories from a GitHub connection within an Azure Boards project.
    • Completely remove a GitHub connection for a project.
    • Allow a GitHub repository to connect to one or more Azure Boards projects within the same Azure DevOps organization or collection.

Azure Boards-GitHub integration supports the following operational tasks:

  • Create links between work items and GitHub commit, pull requests, and issues based on GitHub mentions
  • Support state transition of work items to a "Done" or "Completed" state when using GitHub mention by using fix, fixes, or fixed
  • Support full traceability by posting a discussion comment to GitHub when linking from a work item to a GitHub commit, pull requests, or issue
  • Show linked to GitHub code artifacts within the work item Development section
  • Show linked to GitHub artifacts as annotations on Kanban board cards
  • Support status badges of Kanban board columns added to GitHub repositories.

The following tasks aren't supported at this time:

  • Query for work items with links to GitHub artifacts. However, you can query for work items with an External Link Count > 0.

Connect Azure Boards to GitHub repositories

You can start from Azure Boards or from GitHub to make the connection. You can connect up to 250 GitHub repositories to an Azure Boards project.

You can start from Azure Boards or from GitHub to make the connection. You can connect up to 100 GitHub repositories to an Azure Boards project.

Note

We recommend that you use the Azure Boards app for GitHub to configure and manage your connections to GitHub.com. The app provides a more streamlined configuration experience and has the advantage of authenticating and operating as the app rather than an individual. Once you have configured your connection, you can manage the connected repositories either from Azure Boards or GitHub.com.

To start from GitHub

To start from Azure Boards

  • Connect Azure Boards to GitHub (Cloud):
    • Add a connection from an Azure Boards project to select GitHub repositories
    • Approve and install the Azure Boards app for GitHub for your GitHub account or organization

Exercise Azure Boards-GitHub integration features

Once you've configured the connection, you can complete the following tasks.

Add or remove connections

Restrictions

  • Only connect a GitHub repository to one Azure DevOps organization and project.
    Connecting the same GitHub repo to projects defined in two or more Azure DevOps organizations can lead to unexpected AB# mention linking. For details, see Troubleshoot GitHub & Azure Boards integration.