Connect an on-premises Azure DevOps Server to a GitHub repo

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

By connecting 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.

To connect to GitHub.com repositories, you must install Azure DevOps Server 2020.1.1 Patch 2. Without this patch, you can only connect to your GitHub Enterprise Server repositories.

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.

By connecting 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

Authentication options

The following authentication options are supported.

Note

OAuth is no longer 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 details, see Creating an OAuth App.

Register Azure DevOps Server

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

    Sign into GitHub Enterprise server

  2. Open Settings>Developer settings>Oauth Apps and choose New OAuth App.

    Open Settings>Developer settings>Oauth Apps and choose New OAuth App.

  3. Fill out the form to register your Azure DevOps Server application.

    Register your Azure DevOps Server project

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

    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

    Or,

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

  4. Choose Register application.

  5. Upon success, you'll see a page that provides the Client ID and Client Secret for your registered OAuth application.

    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. Open Admin settings>Oauth configurations, and choose Add Oauth configuration.

    Admin Settings>OAuth configurations

  4. Fill in the form that appears, and then choose Create.

    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. Choose 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. Choose (1) Project Settings> (2) 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, choose New connection, and select your authentication method from the New Connection dialog.

  1. Choose (1) Project Settings> (2) GitHub connections, and then (3) Connect your GitHub Enterprise account.

    Project Settings>Integrations

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

Connect using OAuth

Connect using a Personal Access Token

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

    Tip

    When creating 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 choose Connect.

    Sign in with personal access token.

Connect using 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.

    Sign in with username and password.

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

    Choose repositories to add.

  3. If you're connecting to a GitHub account or organization from Azure Boards for the first time, you'll also be installing the Azure Boards app for GitHub. Complete the integration by following the procedures outlined in Confirm the connection.

Resolve connection issues

See Troubleshoot GitHub repository connection.

Try this next