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

• 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 you'll connect to.

Authentication options

The following authentication options are supported.

• PAT
• Username plus password

Note

OAuth is no longer supported for Azure DevOps Server 2020.

• OAuth (Recommended, registration required)
• PAT
• Username plus password

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.

   

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

   

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

   

   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.

   

   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.

   

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.

   

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

   

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.

   

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:

   • Personal Access Token, for details see Connect using a Personal Access Token.
   • User Name and Password, see Connect using a Username and Password.

   

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

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

   

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

Connect using OAuth

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

  

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.

   

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.

   

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.

   

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

Link GitHub commits and pull requests to work items

Related articles

• Add or remove GitHub repositories
• What is Azure Boards?
• Troubleshoot GitHub & Azure Boards integration
• Build GitHub Enterprise Server repositories
• Trigger an Azure Pipelines run from GitHub Actions