Connect Azure DevOps Server to GitHub (on-premises)

Azure DevOps Server 2022 | Azure DevOps Server 2020 | Azure DevOps Server 2019

Prerequisites

• Integration with GitHub:
  • Connect to GitHub.com repositories by installing Azure DevOps Server 2020.1.1 Patch 2. Without this patch, you can only connect to your GitHub Enterprise Server repositories.
  • Install the Azure Boards app for GitHub on the GitHub organizations or account.
• Project connection: Connect to an Azure Boards or Azure DevOps project. If you don't have a project yet, create one.
• Permissions:
  • Be a member of the Project Collection Administrators group and the project's Contributors group. If you created the project, then you have permissions.
  • Be an administrator of the GitHub Enterprise Server that you connect to.

Authentication options

The following authentication options are supported.

Connect Azure DevOps Server to GitHub Enterprise Server

1. Open the web portal for your Azure DevOps Server.

2. Select the Azure DevOps logo to open Projects, and then choose the Azure Boards project you want to configure to connect to your GitHub Enterprise repositories.

Connect with a Personal Access Token

1. To create a PAT, see Creating a personal access token.

   Tip

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

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

Connect with a username and password

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

2. 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 you're done.

   

3. To connect to a GitHub account or organization from Azure Boards for the first time, you also install the Azure Boards app for GitHub. Complete the integration by following the procedures outlined in Confirm the connection.

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 integrate with GitHub.com and GitHub Enterprise Server repositories. Azure DevOps Server 2019 and later versions support integration with GitHub Enterprise Server repositories only. Integration with other Git repositories is not supported.

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.

Consider the following resolutions:

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

    • GitHub
    • Azure DevOps

    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 might be revoked or the required permission scopes changed and are insufficient.

  • The user perhaps lost administrative permissions on the GitHub repository.

    Recreate the PAT and ensure the scope for the token includes the required permissions: repo, read:user, user:email, admin:repo_hook.

Update XML definitions for select work item types

If your organization customizes work tracking using the Hosted XML or on-premises XML process model and wants to integrate GitHub link types into the Development section of work item forms, you must update the XML definitions for the corresponding work item types.

For example, to link user stories and bugs to GitHub commits and pull requests within the Development section of work item forms, you must update the XML definitions for these work item types.

To modify the XML definitions, do the steps outlined in Hosted XML process model. For each work item type:

1. Locate the Group Label="Development" section.
2. To support the external link types, GitHub Commit and GitHub Pull Request, add the following lines of code:

This integration enables seamless tracking of GitHub activities directly from your work items in Azure Boards.

             <ExternalLinkFilter Type="GitHub Pull Request" />  
             <ExternalLinkFilter Type="GitHub Commit" />  

When it updates, 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

Link GitHub commits and pull requests to work items

Related articles

• Learn about Azure Boards?
• Troubleshoot GitHub & Azure Boards integration
• Build GitHub Enterprise Server repositories