Install the Azure Boards app for GitHub

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

Install the Azure Boards app for GitHub to connect Azure Boards to your GitHub repositories. When you connect Azure Boards projects with repositories, you support linking between GitHub commits and pull requests to work items. You can use GitHub for software development while using Azure Boards to plan and track your work.

For an overview of the integration that the Azure Boards app for GitHub supports, see Azure Boards-GitHub integration. Once you install the Azure Boards app for GitHub on your GitHub account or organization, choose which GitHub repositories you want to connect to from your project.


  • To install the Azure Boards app, you must be an administrator or owner of the GitHub organization.
  • To connect to the Azure Boards project, you must have read permission to the GitHub repository. Also, you must be a member of the Project Collection Administrators group. If you created the project, then you have permissions.


If your repository is already connected via another authentication type such as OAuth, you must remove that repository from your existing connection before you re-connect it via the GitHub App. Follow the steps provided in Add or remove GitHub repositories later in this article before you configure the GitHub App.

You can connect an Azure DevOps organization to multiple GitHub repositories if you're an administrator for those repositories. However, you shouldn't connect a GitHub repository to more than one Azure DevOps organization.

Give Azure Boards organization access

Do the following steps to grant organization access.

  1. From the GitHub web portal, open Settings from your profile menu.

    Screenshot of open profile, choose Settings.

  2. Select Applications under Integrations.

  3. Select Authorized OAuth Apps > Azure Boards.

    Screenshot of Authorized OAuth Apps tab, choose Azure Boards.

  4. Under Organization access, resolve any issues that may appear. Select Grant to grant access to any organizations that show as having an Access request pending.

    Screenshot of Organization access with organizations without access.

Install and configure the Azure Boards app

  1. Go to the Azure Boards app in the GitHub Marketplace.

  2. Select Set up a plan.

    Screenshot of GitHub Marketplace, Set up a plan button.

  3. Choose the GitHub organization you want to connect to Azure Boards.

    Screenshot showing Install Azure Boards dialog.

  4. Choose the repositories that you want to connect to Azure Boards.

    Here we choose to connect to all repositories.

    Screenshot showing all repositories selected.

  5. Choose the Azure DevOps organization and Azure Boards project you want to connect to

    Screenshot of Setup your Azure Boards project dialog.

    You can only connect one project at a time. If you have other projects you want to connect, you can do that later as described in Configure other projects or repositories later in this article.

  6. Authorize your Azure Boards organization to connect with

    Screenshot of Azure Boards authorization dialog.

  7. Confirm the repositories that you want to connect. Select each repository you want to connect to. Unselect any repositories that you don't want to participate in the integration.

    Screenshot of Confirm your GitHub repositories dialog.

Use the connection

At this point, your Azure Boards-GitHub integration is complete. You can skip the next steps or run through them to understand the features supported with the connection.

  1. Select Create to add a work item—Issue (Basic), User Story (Agile), or Product Backlog Item (Scrum)—depending on the process model used by your Azure Boards project.

    Screenshot of the Get started, Create issue dialog.

    A work item titled Add badge to README appears on your Azure Boards.

  2. Select Create and link a pull request.

    Success screenshot, GitHub repo is connected to Azure Boards.

    This step runs the following actions in the background:

    • Adds a badge to the README file of the first repository in the list of connected GitHub repositories
    • Creates a GitHub commit for the update made by adding the badge to the README file
    • Creates a GitHub pull request to merge the changes made to the README file
    • Links the GitHub commit and pull request to the work item created in step 1.
  3. Select View work item to open the work item you created in step 1. Note the links under the Development section that correspond to the commit and pull request created in

    Screenshot of viewing work item.

  4. Choose the pull request link, the first link in the list, to open the pull request in GitHub.

    The GitHub pull request opens in a new browser tab.

Screenshot of issue form.

  1. Complete the pull request.

    Screenshot of example PR.

  2. Go to your repository README file and view the badge that was added.

    Screenshot of GitHub repo with badge added.

    For more information, see Configure status badges to add to GitHub README files.

Configure other projects or repositories

You can configure other Azure Boards/Azure DevOps Projects, repositories, or change the current configuration from the Azure Boards app page. For more information, see Change GitHub repository access, or suspend or uninstall the integration.

Add or remove repositories, or remove a connection from Azure Boards

If you encounter a problem with a connection, we recommend that you remove the connection and start over with a new connection.

  1. To add or remove repositories, choose More options for the connection and choose Add repositories or Remove repositories from the menu.

    Screenshot of GitHub connection menu of More options.

  2. To remove all repositories and the connection, choose the Remove connection option. Then, choose Remove to confirm.

    Screenshot of confirmation removal of GitHub connection.

  1. To add or remove repositories, open the actions icon for the connection and choose Add repositories or Remove repositories from the menu.

    Screenshot of add or remove GitHub repos.

  2. To remove all repositories and the connection, choose the Remove connection option. Then, choose Remove to confirm.

    Screenshot of confirmation of GitHub connection removal dialog.

Change repository access

  1. Sign into the web portal for your GitHub organization and open Account settings.

  2. Choose Installed GitHub Apps and then Configure next to Azure Boards.
    Screenshot of open Organization account, Installed GitHub Apps, Azure Boards, Configure.

    The Azure Boards configuration page opens.

  3. Scroll down to the Repository access section.

  4. Choose the option you want, All repositories or Only select repositories.

    If you choose Only select repositories, select the repositories you want to participate in integration with Azure Boards.

    Screenshot of Repository access, choose Only select repositories.

  5. Choose Save when you're done.

Suspend or uninstall Azure Boards integration

  1. Starting from step 2 in the previous procedure, scroll down to the Danger zone section.

    Screenshot of Azure Boards configuration, Danger zone section.

  2. To suspend the integration, choose Suspend. From the popup confirmation window, choose OK to confirm the suspension.

    Screenshot of suspension confirmation.

    To unsuspend the integration, choose Unsuspend.

  3. To uninstall the Azure Boards app, choose Uninstall, and then choose OK from the popup confirmation window.

    Screenshot of uninstall confirmation.

Update Azure Boards-GitHub connections

If you change the repositories that the Azure Boards app for GitHub supports, you may be redirected to Azure Boards GitHub connections. A good practice is to remove the repositories in Azure Boards that can no longer connect to GitHub. For more information, see Add or remove GitHub repositories.

If you uninstall the Azure Boards app for GitHub, you'll see the following message in Azure Boards, Project Settings>GitHub Connections. Choose Remove connection to remove all GitHub connections that have been previously made. See also, Add or remove GitHub repositories.

Screenshot of uninstalled Azure Boards GitHub app.

Next steps