Connect Azure Boards to GitHub (cloud)
Azure DevOps Services
Use GitHub.com repositories for your software development and your Azure Boards project to plan and track your work. Connect your project and repo so your GitHub commits and pull requests get linked to your work items in Azure Boards.
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
- You must have 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 to connect to. You can connect to multiple GitHub repositories as 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
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.
Connect Azure Boards to a GitHub repo.
Sign into your Azure DevOps project.
Select Project settings > GitHub connections.
If it's the first time you make 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. To use PAT, see Add a GitHub connection using PAT. To connect 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 500 GitHub repositories to an Azure Boards project.
If it's your first time connecting to GitHub from Azure Boards, you're asked to sign in using your GitHub credentials. Choose an account for which you're a repository administrator.
Choose the GitHub account or organization that 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 see the following message.
Enter your GitHub credentials. If you have two-factor authentication enabled, enter the authentication code that GitHub sent you and choose Verify. Otherwise, the system automatically recognizes your GitHub organization as your GitHub account has previously been associated with your Azure DevOps Services account.
Choose the repositories
Once you're 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 more information, see Troubleshoot GitHub & Azure Boards integration.
If all repositories are connected already to the current or other organization, then the following message displays.
When you're done, select Save.
Confirm the connection
Review the GitHub page that displays and then choose Approve, Install, & Authorize.
Provide your GitHub password to confirm.
When you're 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 you create your GitHub PAT, make sure that you include these scopes: repo, read:user, user:email, admin:repo_hook
.
Choose Personal Access Token.
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 also must install the Azure Boards app for GitHub. 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 with your GitHub Enterprise Server, you first need to register the application as an OAuth App. For more information, see Create an OAuth App.
Register Azure DevOps Services
Sign into the web portal for your GitHub Enterprise server.
Open Settings > Developer settings > Oauth Apps > New OAuth App.
Enter information to register your 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
Select Register application.
The Client ID and Client Secret for your registered OAuth application appear.
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.
In Organization settings, select Oauth configurations > Add Oauth configuration.
Enter your information, and then select 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 Data Center 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.
Select Project settings > GitHub connections > GitHub Enterprise Server for a first-time connection.
Or, from the New GitHub connection dialog, select GitHub Enterprise Server.
Select the authentication method.
Connect with 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 with 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 with a Username and Password
Enter the URL for your GitHub Enterprise server and the administrator account credentials recognized by that server, and then select Connect.
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. Select Save when you're 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 also install the Azure Boards app for GitHub. Confirm the connection earlier in this article.
Resolve connection issues
The Azure Boards-GitHub integration relies on various authentication protocols to support the connection. Changes to a user's permission scope or authentication credentials can cause revocation of the GitHub repositories connected to Azure Boards.
For an overview of the integration that the Azure Boards app for GitHub supports, see Azure Boards-GitHub integration.
Supported authentication options
The following authentication options are supported based on the GitHub platform you want to connect to.
Platform
GitHub.com
GitHub Enterprise Server
Azure DevOps Services
- GitHub.com user account
- Personal access token (PAT)
- OAuth
- PAT
- Username plus password
Azure DevOps Server 2020
Not applicable
- PAT
- Username plus password
Azure DevOps Server 2019
Not applicable
- OAuth
- PAT
- Username plus password
Note
With the Azure Boards app for GitHub, Azure Boards and Azure DevOps Services support integration with GitHub.com and GitHub Enterprise Server repositories. Azure DevOps Servers 2019 and later versions support integration with GitHub Enterprise Server repositories only.Integration with other Git repositories is not supported.
Grant Azure Boards organization access
If the integration between Azure Boards and GitHub isn't working as expected, verify you've granted organization access.
From GitHub web portal, open Settings from your profile menu.
Select Applications under Integrations > Authorized OAuth Apps > Azure Boards.
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.
Resolve access issues
When the Azure Boards connection to GitHub no longer has access, it shows an alert status in the user interface with a red-X. Hover over the alert and it indicates that the credentials are no longer valid. To correct the problem, remove the connection and recreate a new connection.
To resolve this issue, consider the following items:
If the connection is using OAuth:
The Azure Boards application had its access denied for one of the repositories.
GitHub might be unavailable/unreachable. This unavailability could be because of an outage in either service or an infrastructure/network issue on-premises. You can check service status from the following links:
Delete and recreate the connection to the GitHub repository. This recreated connection causes GitHub to prompt to reauthorize Azure Boards.
If the connection is using a PAT:
The PAT may have been revoked or the required permission scopes changed and are insufficient.
The user may have lost admin permissions on the GitHub repo.
Recreate the PAT and ensure the scope for the token includes the required permissions:
repo, read:user, user:email, admin:repo_hook
.
Resolve broken GitHub Enterprise Server connection
If you've migrated from Azure DevOps Server to Azure DevOps Services with an existing GitHub Enterprise Server connection, your existing connection won't work as expected. Work item mentions within GitHub may be delayed or never show up in Azure DevOps Services. This problem occurs because the callback url associated with GitHub is no longer valid.
Consider the following resolutions:
Remove and re-create the connection: Remove and re-create the connection to the GitHub Enterprise Server repository. Follow the sequence of steps provided in Connect from Azure Boards documentation.
Fix the webhook url: Go to GitHub's repository settings page and edit the webhook url to point out to the migrated Azure DevOps Services organization url:
https://dev.azure.com/{OrganizationName}/_apis/work/events?api-version=5.2-preview
Connect to multiple Azure DevOps organizations
If you connect your GitHub repository to two or more projects that are defined in more than one Azure DevOps organization, such as dev.azure.com/Contoso and dev.azure.com/Fabrikam, you may get unexpected results when using AB# mentions to link to work items. This problem occurs because work item IDs aren't unique across Azure DevOps organizations, so AB#12 can refer to a work item in either the Contoso or Fabrikam organization. So, when a work item is mentioned in a commit message or pull request, both organizations attempt to create a link to a work item with a matching ID (if one exists).
In general, a user intends an AB# mention to link to a single work item in one of the projects. But, if a work item of the same ID exists in both accounts, then links get created for both work items, likely causing confusion.
Currently, there's no way to work around this issue, so we recommend that you connect a single GitHub repository only to a single Azure DevOps organization.
Note
When you make the connection by using the Azure Boards app for GitHub, the app prevents you from connecting to two different organizations. If a GitHub repository is incorrectly connected to the wrong Azure DevOps organization, you must contact the owner of that organization to remove the connection before you can add the repository to the correct Azure DevOps organization.
Update XML definitions for select work item types
If your organization uses the Hosted XML or On-premises XML process model to customize the work tracking experience and you want to link to and view the GitHub link types from the Development section in the work item forms, you'll need to update the XML definitions for the work item types.
For example, if you want to link user stories and bugs to GitHub commits and pull requests from the Development section, you need to update the XML definitions for user stories and bugs.
Follow the sequence of tasks provided in Hosted XML process model to update the XML definitions. For each work item type, find the Group Label="Development"
section, and add the following two lines in the following code syntax to support the external links types: GitHub Commit and GitHub Pull Request.
<ExternalLinkFilter Type="GitHub Pull Request" />
<ExternalLinkFilter Type="GitHub Commit" />
When it's updated, the section should appear as follows.
<Group Label="Development">
<Control Type="LinksControl" Name="Development">
<LinksControlOptions ViewMode="Dynamic" ZeroDataExperience="Development" ShowCallToAction="true">
<ListViewOptions GroupLinks="false">
</ListViewOptions>
<LinkFilters>
<ExternalLinkFilter Type="Build" />
<ExternalLinkFilter Type="Integrated in build" />
<ExternalLinkFilter Type="Pull Request" />
<ExternalLinkFilter Type="Branch" />
<ExternalLinkFilter Type="Fixed in Commit" />
<ExternalLinkFilter Type="Fixed in Changeset" />
<ExternalLinkFilter Type="Source Code File" />
<ExternalLinkFilter Type="Found in build" />
<ExternalLinkFilter Type="GitHub Pull Request" />
<ExternalLinkFilter Type="GitHub Commit" />
</LinkFilters>
</LinksControlOptions>
</Control>
</Group>
Next steps
Related articles
Feedback
Submit and view feedback for