Note
Access to this page requires authorization. You can try signing in or changing directories.
Access to this page requires authorization. You can try changing directories.
Azure DevOps Services | Azure DevOps Server 2022 | Azure DevOps Server 2020
In this quickstart, you install the Azure Boards app for GitHub to connect Azure Boards to your GitHub repositories. When you connect 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. After 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.
For an overview of the integration that the Azure Boards app for GitHub supports, see Azure Boards-GitHub integration.
Prerequisites
| Category | Requirements |
|---|---|
| Permissions | - Member of the Project Collection Administrators group. If you created the project, you have permissions. - Administrator or owner of the GitHub organization for installing the Azure Boards app. - Read permissions for the GitHub repository. |
| Project membership | Project member. |
Important
If your repository is already connected by using another authentication type such as OAuth, you must remove that repository from your existing connection before you reconnect it by using 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. You shouldn't connect a GitHub repository to more than one Azure DevOps organization.
Install and configure the Azure Boards app
Your installation sequence might vary due to your account configuration. If necessary, follow on screen prompts between the following steps.
Go to the Azure Boards app in the GitHub Marketplace.
Under Plans and pricing, under Free, select Install.
In Install & Authorize Azure Boards, choose the repositories that you want to connect to Azure Boards, then select Install & Authorize.
This example uses All repositories:
Choose the Azure DevOps organization and Azure Boards project you want to connect to GitHub.com.
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.
Give Azure Boards organization access
If necessary, to grant GitHub access to your Azure DevOps organization, do the following steps.
From the GitHub web portal, open Settings from your profile menu.
Select Applications under Integrations.
Select Authorized GitHub Apps > Azure Boards.
Under Organization access, resolve any issues that might appear. Select Grant to grant access to any organizations that show as having an Access request pending.
Use the connection
At this point, your Azure Boards-GitHub integration is complete. You can skip the next steps or go through them to understand the features supported with the connection.
On your board, select New work item to enter a new work item named "Add badge to README"—Issue (Basic), User Story (Agile), or Product Backlog Item (Scrum)—depending on the process model used by your Azure Boards project.
A work item titled Add badge to README appears on your board.
Open your work item, go to the Development section, and select Add link.
From Link type, select GitHub Pull Request.
Select the repository and enter the pull request ID and an optional comment.
Select Add link.
The following actions occur in the background, automatically:
- 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.
Select the first pull request link from your work item.
The GitHub pull request opens in a new browser tab.
Select Merge pull request.
Go to your repository README file and view the badge that was added.
For more information, see Add status badges for your GitHub repo.
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. For more information, see Add or remove repositories, or remove a connection from Azure Boards.
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.
From your project in Azure DevOps, go to Project settings > GitHub connections.
To add or remove repositories, select the More options ellipses for the connection and choose Add repositories or Remove repositories from the menu.
To remove all repositories and the connection, choose the Remove connection option. Then, choose Remove to confirm.
Change repository access
From the GitHub web portal, open Settings from your profile menu.
Select Integrations > Applications. Under Installed GitHub Apps, select Configure.
The Azure Boards configuration page opens.
Scroll down to the Repository access section.
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.
Select Save.
Suspend or uninstall Azure Boards integration
Starting from step 2 in the previous procedure, scroll down to the Danger zone section.
To suspend the integration, choose Suspend. From the confirmation window, choose OK to confirm the suspension.
To unsuspend the integration, choose Unsuspend.
To uninstall the Azure Boards app, choose Uninstall, and then choose OK from the popup confirmation window.
Update Azure Boards-GitHub connections
If you change the repositories that the Azure Boards app for GitHub supports, you might get 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, the following message displays in Azure Boards, Project settings > GitHub connections. Choose Remove connection to remove all previously made GitHub connections. For more information, see Add or remove GitHub repositories.
