Connect Azure Boards to GitHub (Cloud)

Article
02/24/2023
7 minutes to read

Azure DevOps Services

To support linking of GitHub commits and pull requests to Azure Boards work items, you connect your Azure Boards project to GitHub.com repositories. Then, use GitHub for software development while using Azure Boards to plan and track your work. For an overview of the Azure Boards app for GitHub, see Azure Boards-GitHub integration.

When you make the connection from Azure Boards, the list of GitHub repositories corresponds to ones that you allow Azure Boards to access. You can limit which repositories Azure Boards accesses overall, and limit what a particular project accesses or split the management of work across different Azure Boards projects.

Note

Azure Boards and Azure DevOps Services support integration with GitHub.com and GitHub Enterprise Server repositories. If you want to connect from an on-premises Azure DevOps Server, see Connect Azure DevOps Server to GitHub Enterprise Server.

Prerequisites

Connect to an Azure Boards or Azure DevOps project. If you don't have a project yet, create one.
You must be a member of the Project Administrators group. If you created the project, you have permissions.
You must be an administrator or owner of the GitHub repository you'll connect to. You can connect to multiple GitHub repositories so long as you're an administrator for those repositories.

Authentication options

The following authentication options are supported based on the GitHub platform you want to connect to.

GitHub.com

GitHub Enterprise Server

GitHub.com user account (Recommended)
Personal access token (PAT)

OAuth (preferred, registration required)
PAT
Username plus password

Note

If you choose to connect Github with PAT, make sure you configure single sign-on (SSO) for the PAT on your GitHub account. This is needed to be able to get a list of repositories of an organization with Security Assertion Markup Language (SAML) SSO authentication configured.

Open Project Settings>GitHub Connections.

Sign into Azure Boards for the project you want to connect to GitHub repositories.
Choose (1) Project Settings> (2) GitHub connections.
If it's the first time making a connection from the project, choose Connect your GitHub account to use your GitHub account credentials.

Otherwise, choose New connection, and select your authentication method from the New Connection dialog.

When you connect using your GitHub account, use your GitHub account credentials to authenticate. If connecting using PAT, see Add a GitHub connection using PAT. If connecting to a GitHub Enterprise Server, see Register Azure DevOps in GitHub as an OAuth App.

Add a GitHub connection with GitHub credentials

You can connect up to 250 GitHub repositories to an Azure Boards project.

If it's your first time connecting to GitHub from Azure Boards, you'll be asked to sign in using your GitHub credentials. Choose an account for which you're an administrator for the repositories you want to connect to.
If you belong to more than one GitHub account or organization, choose the one whose repositories you want to connect. Only those organizations that you own or are an administrator for are listed.

If all repositories for an organization have already been connected to Azure Boards, you'll see the following message.
When asked, enter your GitHub credentials.

If you have enabled two-factor authentication, enter the authentication code that GitHub sent you and choose Verify.

Otherwise, the system will automatically recognize your GitHub organization as your GitHub account has previously been associated with your Azure DevOps Services account.

Choose the repositories

Once you've been authenticated, you can select the repositories you want to connect.

The Add GitHub Repositories dialog automatically displays and selects all GitHub.com repositories for which you're an administrator for the organization you selected. Unselect any repositories that you don't want to participate in the integration.

Tip

We recommend that you only connect a GitHub repo to projects defined in a single Azure DevOps organization. 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.

If all repositories have been connected already to the current or other organization, then the following message displays.
When done, choose Save.

Confirm the connection

In this step, you install the Azure Boards app for GitHub on the GitHub account or organization associated with the repositories you chose to connect to.

Review the GitHub page that displays and then choose Approve, Install, & Authorize.
Provide your GitHub password to confirm.
When done, you should see the new connection with the selected repositories listed.

To change the configuration or manage the Azure Boards app for GitHub, see Change repository access to Azure Boards.

Add a GitHub connection using PAT

We recommend that you use your GitHub account credentials to connect to your GitHub repository. However, if you need to use a PAT, do so by following these procedures.

Tip

When creating your GitHub PAT, make sure that you include these scopes: repo, read:user, user:email, admin:repo_hook.

To choose a PAT when connecting a GitHub repository, choose Personal Access Token when making a first-time connection.

Or, from the New GitHub connection dialog.

To create a GitHub PAT, go to GitHub Developer Settings>Personal access tokens.
Enter the PAT and choose Connect.
Choose the repositories you want connected to the project by following the procedures outlined in Choose the repositories earlier in this article.
If it's the first time connecting to a GitHub account or organization from Azure Boards, you'll also be installing the Azure Boards app for GitHub. Complete the integration by following the procedures outlined in Confirm the connection earlier in this article.

Register Azure DevOps in GitHub as an OAuth App

If you plan to use OAuth to connect Azure DevOps Services or Azure DevOps Server with your GitHub Enterprise Server, you first need to register the application as an OAuth App. For details, see Creating an OAuth App.

Register Azure DevOps Services

Sign into the web portal for your GitHub Enterprise server.
Open Settings>Developer settings>Oauth Apps and choose New OAuth App.
Fill out the form to register your Azure DevOps Server application.

For the Homepage URL, specify the Organization URL of your organization.
For the Authorization callback URL, use the following pattern to construct the URL.

{Azure DevOps Services Organization URL}/_admin/oauth2/callback

For example:

https://dev.azure.com/fabrikam/_admin/oauth2/callback
Choose Register application.
Upon success, you'll see a page that provides the Client ID and Client Secret for your registered OAuth application.

Register your OAuth configuration in Azure DevOps Services

Sign into the web portal for Azure DevOps Services.
Add the GitHub Enterprise Oauth configuration to your organization.
Open Organization settings>Oauth configurations, and then choose Add Oauth configuration.
Fill in the form that appears, and then choose Create.

Connect Azure DevOps Services to GitHub Enterprise Server

Important

To connect Azure DevOps Services to your GitHub Enterprise Server, your GitHub Enterprise Server must be sufficiently accessible from the Internet. Make sure Azure DNS can resolve your GitHub Enterprise Server name and your firewall allows access from Azure Data Center IP addresses. To determine the IP address range, see Microsoft Azure Datacenter IP Ranges. A common error message encountered when connectivity issues exist is:

The remote name could not be resolved: 'github-enterprise-server.contoso.com'

If you encounter this error, check that your server is accessible. For more information, see Azure DNS FAQ.

From the Project Settings>GitHub connections page choose GitHub Enterprise Server, choose GitHub Enterprise Server when making a first-ptime connection.

Or, from the New GitHub connection dialog, choose GitHub Enterprise Server.
Select the authentication method.

Connect using OAuth

Choose the configuration that you set up in Step 4 of Register your OAuth configuration in Azure DevOps Services, and then choose Connect.

Connect using a Personal Access Token

Enter the URL for your GitHub Enterprise server and the Personal access token credentials recognized by that server. And then choose Connect.

Connect using a Username and Password

Enter the URL for your GitHub Enterprise server and the administrator account credentials recognized by that server. And then choose Connect.

Choose the repositories to connect to
The dialog lists all repositories for which you have GitHub administration rights. You can toggle between Mine and All to determine if others appear, and then check the ones that you want to add. Choose Save when done.

Tip

You can only make a connection to repositories defined under one GitHub organization. To connect a project to other repositories defined in another GitHub organization, you must add another connection.
If it's your first time connecting to a GitHub account or organization from Azure Boards, you'll also be installing the Azure Boards app for GitHub. Complete the integration by following the procedures outlined in Confirm the connection earlier in this article.