title: Install the Azure Boards app for GitHub titleSuffix: Azure Boards description: Configure the Azure Boards app to connect one or more GitHub repositories to Azure Boards ms.assetid: ms.prod: devops ms.technology: devops-agile ms.topic: quickstart ms.manager: mijacobs ms.author: kaelli author: KathrynEE monikerRange: 'azure-devops' ms.date: 06/28/2019
[!INCLUDEtemp]
By installing the Azure Boards app for GitHub, you can configure and manage the connections of your Azure Boards projects (hosted service only) with your GitHub.com 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.
While the steps to make the GitHub-Azure Boards connection are different depending on your starting point, the end result is the same. You can connect from Azure Boards or use the instructions provided in this article to connect from GitHub.
This article walks you through the following 5 minute installation and configure process:
- Install and configure
- Choose the GitHub.com repositories you want to connect
- Choose the Azure DevOps Services organization and Azure Boards project you want to connect
- Authorize connection to Azure Boards
- Confirm the repositories you want to connect
- (Optional) Get started
- In Azure Boards, create a work item for adding a badge to your GitHub.com repo README file
- In GitHub.com, add the badge syntax to a repo README file, commmit the change, and create a pull request for the commit
- In Azure Boards, add links to the GitHub commit and pull request to the work item; choose the GitHub pull request link to open the pull request in GitHub.com
- In GitHub.com, complete the pull request and view the badge added to your GitHub repo
You can learn more about the Azure Boards app from the GitHub Marketplace, and Azure Boards from Azure DevOps Services>Azure Boards.
- You must be an administrator or owner of the GitHub repository you'll be connecting to.
- To install the Azure Boards app, you must be an administrator or owner of the GitHub repository or GitHub organization.
- To connect to the Azure Boards project, you must have read permission to the GitHub repository.
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 in the remove repositories section 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 can't connect a GitHub repository to more than one Azure Boards project. To understand why, review Troubleshoot GitHub & Azure Boards connection, Unexpected results when linking to projects defined in two or more Azure DevOps organizations.
-
Go to the Azure Boards app in the GitHub Marketplace.
[!div class="nextstepaction"] Azure Boards app
-
Choose Set up a plan.
[!div class="mx-imgBorder"]
-
Choose the GitHub organization you want to connect to Azure Boards.
[!div class="mx-imgBorder"]
-
Choose the repositories you want to connect to Azure Boards.
Here we choose to connect to all repositories.
[!div class="mx-imgBorder"]
-
Choose the Azure DevOps organization and Azure Boards project you want to connect to GitHub.com.
[!div class="mx-imgBorder"]
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 additional projects or repositories later in this article.
-
Authorize your Azure Boards organization to connect with GitHub.com.
[!div class="mx-imgBorder"]
-
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.
[!div class="mx-imgBorder"]
At this point, your Azure Boards + GitHub connection is complete. You can skip the next steps or run through them to understand the features supported with the connection.
-
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.
[!div class="mx-imgBorder"]
A work item titled Add badge to README appears on your Azure Boards.
-
Next, choose Create and link a pull request.
[!div class="mx-imgBorder"]
This step performs 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.
-
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
[!div class="mx-imgBorder"]
-
Choose the pull request link (first link in the list) to open the pull request in GitHub.
The GitHub pull request opens in a new browser tab.
[!div class="mx-imgBorder"]
-
Go ahead and complete the pull request.
[!div class="mx-imgBorder"]
-
Navigate to your repository README file and view the badge that has been added.
[!div class="mx-imgBorder"]
To learn more about Azure Boards badges, see Configure status badges to add to GitHub README files.
You can configure additional Azure Boards/Azure DevOps projects, GitHub.com repositories, or change the current configuration from the Azure Boards app page.
Note
The Azure Boards app prevents you from connecting a GitHub repo to more than one Azure Boards/Azure DevOps organization. You can, however, connect a repo to two or more projects within the same organization. To learn more, see Troubleshoot GitHub & Azure Boards connection.
-
Open the Azure Boards app page.
[!div class="mx-imgBorder"]
-
Choose Configure.
-
To add repositories, scroll down the page and choose each repository to add from the Select repositories drop-down menu.
[!div class="mx-imgBorder"]
-
Follow steps 5 through 7 provided under the Install and configure section earlier in this article.
-
Open the Azure Boards app page.
-
Choose Configure.
-
Scroll down and choose Uninstall.
[!div class="mx-imgBorder"]
-
Confirm that you understand that uninstalling the Azure Boards app will remove all connections you've made to connect to GitHub repositories.
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.
-
From you Azure Boards project web portal, choose (1) Project Settings, expand Boards as needed, and then choose (2) GitHub connections.
[!div class="mx-imgBorder"]
-
To add or remove repositories, open the
actions icon for the connection and choose Add repositories or Remove repositories from the menu.[!div class="mx-imgBorder"]
-
To remove all repositories and the connection, choose the Remove connection option. Then, choose Remove to confirm.
[!div class="mx-imgBorder"]
[!div class="nextstepaction"] Link GitHub commits and pull requests to work items