Edit

Connect Azure DevOps Server to GitHub (on-premises)

  • Article

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

When you connect your Azure DevOps Server project to your GitHub 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.

Note

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

When you connect your Azure DevOps Server project with your GitHub Enterprise Server repositories, you support linking between GitHub commits and pull requests to work items. You can use GitHub Enterprise for software development while using Azure Boards to plan and track your work.

Note

On-premises Azure DevOps Server 2019 supports integration with GitHub Enterprise Server repositories. If you want to connect from Azure DevOps Services, see Connect Azure Boards to GitHub.

Prerequisites

  • 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.
  • 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 Collection Administrators group and the project's Contributors group. If you created the project, then you have permissions.
  • You must be an administrator of the GitHub Enterprise Server that you connect to.

Authentication options

The following authentication options are supported.

Note

OAuth isn't supported for Azure DevOps Server 2020.

Register Azure DevOps in GitHub as an OAuth App

If you plan to use OAuth to connect Azure DevOps Server 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 Server

  1. Sign into the web portal for your GitHub Enterprise server.

    Screenshot of sign in for GitHub Enterprise Server.

  2. Select Settings > Developer settings > Oauth Apps > New OAuth App.

    Screenshot showing sequence for getting to New OAuth App screen.

  3. Enter your information to register your Azure DevOps Server application.

    Screenshot of Azure DevOps Server project registration.

    For the Homepage URL, specify the Public URL of your project collection. You can find this URL when you open the Azure DevOps Administration Console and viewing the Application Tier node.

    Screenshot of Azure DevOps Server Administration Console, Application Tier.

    For the Authorization callback URL, use the following pattern to construct the URL.

    {Azure DevOps Server Public Url}/{Collection Name}/_admin/oauth2/callback

    For example:

    http://contoso/DefaultCollection/_admin/oauth2/callback

    https://tfs.contoso.com/MyCollection/_admin/oauth2/callback

  4. Select Register application.

  5. A page appears that provides the Client ID and Client Secret for your registered OAuth application.

    Screenshot of Client ID and Client Secret for your registered OAuth application.

Register your OAuth configuration in Azure DevOps Server

  1. Sign into the web portal for your Azure DevOps Server.

  2. Add the GitHub Enterprise Oauth configuration to your Azure DevOps Server collection.

  3. Select Admin settings > Oauth configurations > Add Oauth configuration.

    Screenshot showing step sequence to add OAuth configuration.

  4. Enter your information, and then select Create.

    Screenshot of OAuth configuration dialog.

Connect Azure DevOps Server to GitHub Enterprise Server

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

Note

Connection to more than 100 GitHub repositories requires Azure DevOps Server 2020.1 update or later version.
Connection to GitHub.com repositories requires Azure DevOps Server 2020.1.1 Patch 2 or later version.

You can connect up to 100 GitHub repositories to an Azure Boards project. This limit can't be changed.

  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.

  1. Select Project settings > GitHub connections.

    Screenshot of open Project Settings>GitHub connections.

  2. If it's the first time making a connection from the project, choose the authentication method you want to use to make the connection:

    Screenshot of first time connecting with GitHub credentials.

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

  1. Select Project settings > GitHub connections > Connect your GitHub Enterprise account.

    Screenshot of Project settings, selected Integrations.

    Or, choose a personal access token or username and password, if you're using those credentials.

Connect with OAuth

Choose the configuration that you set up in Step 4 of Register your OAuth configuration in Azure DevOps Server. Then, select Connect.

Screenshot fo New GitHub Enterprise connection, OAuth dialog.

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.

Screenshot of sign in with PAT.

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.

Screenshot of sign in with username and password.

  1. 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.

    Screenshot of repositories to select to add.

  2. 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 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.

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.

Screenshot of failed connection.

When the Azure Boards connection to GitHub no longer has access, it shows an alert status in the user interface with a red-X that has a tooltip such as, Unable to connect to GitHub.

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:

      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.

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 must 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 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