Install the Azure Boards app for GitHub

Azure DevOps Services | Azure DevOps Server 2020 | Azure DevOps Server 2019

Installing the Azure Boards app for GitHub is the first step in connecting Azure Boards to your GitHub repositories. By connecting your Azure Boards projects with GitHub.com 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've installed the Azure Boards app for GitHub on your GitHub account or organization, choose which GitHub repositories you want to connect to from Azure Boards projects.

Prerequisites

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

Important

If your repository is already connected via another authentication type such as OAuth, you'll need to remove that repository from your existing connection before re-connecting it via the GitHub App. Follow the steps provided in Add or remove GitHub repositories before starting the GitHub App configuration.

You can connect an Azure DevOps organization to multiple GitHub repositories so long as you are an administrator for those repositories. However, you shouldn't connect a GitHub repository to more than one Azure DevOps organization. To understand why, review Troubleshoot GitHub & Azure Boards connection, Unexpected results when linking to projects defined in two or more Azure DevOps organizations.

Install and configure the Azure Boards app

  1. Go to the Azure Boards app in the GitHub Marketplace, https://github.com/marketplace/azure-boards.

  2. Choose Set up a plan.

    GitHub Marketplace, Azure Boards

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

    Install Azure Boards, Choose Project

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

    Here we choose to connect to all repositories.

    Install Azure Boards, Choose repositories

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

    Setup Your Azure Boards project, Choose org and project

    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 GitHub.com.

    Authorize Azure Boards

  7. Confirm the GitHub.com 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.

    Confirm your GitHub repositories

Get started with 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. Choose 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.

    Get started, Create issue

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

  2. Next, choose Create and link a pull request.

    Get started, Create linked pull request

    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. Lastly, choose View work item to open the work item created in step 1. Note the links under the Development section that correspond to the commit and pull request created in GitHub.com

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

    Issue form, Add badge

  5. Go ahead and complete the pull request.

    Open GitHub Pull Request link

  6. Navigate to your repository README file and view the badge that has been added.

    GitHub repo with badge added

    To learn more about Azure Boards badges, see Configure status badges to add to GitHub README files.

Configure other projects or repositories

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

Add or remove repositories from Azure Boards

Once you've integrated Azure Boards with GitHub using the Azure Boards app, you can add or remove repositories from the web portal for Azure Boards. To learn how, see Add or remove GitHub repositories.

Try this next