Connect Azure Boards to GitHub

Azure Boards | Azure DevOps Server 2019

By connecting your Azure Boards project with GitHub.com 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.

When you make the connection from Azure Boards, the list of GitHub repositories correspond to ones that you allow Azure Boards to access. You can limit which repositories Azure Boards can access overall, and limit what a particular project can access or split the management of work across different Azure Boards projects.

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

Azure Boards and Azure DevOps Services support integration with GitHub.com and GitHub Enterprise Server repositories.

Azure DevOps Server 2019 supports integration with GitHub Enterprise Server repositories.

Prerequisites

  • You must 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 Administrators group and the project's Contributors group. If you created the project, then you have permissions.
  • You must be an administrator or owner of the GitHub repository you'll be connecting to.

Important

You can connect to multiple GitHub repositories so long as you are an administrator for those repositories.

  • You must 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 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 be connecting to.

Authentication options

Depending on the platform you work from to connect to GitHub, you have a choice of the credentials you use.

Platform GitHub.com GitHub Enterprise Server
Azure DevOps Services
Azure DevOps Server
  • Not supported

Add a GitHub connection

  1. Sign into Azure Boards.

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

    Project Settings>Integrations

    If connecting using PAT, see Add a GitHub connection using PAT. If connecting to a GitHub Enterprise Server, see Register Azure DevOps in GitHub as an OAuth App.

  3. If this is your first time connecting to GitHub from Azure Boards, you will be asked to sign in using your GitHub credentials. Choose an account for which you are an administrator for the repositories you want to connect to.

    GitHub sign in dialog
    If you have enabled two-factor authentication, enter the authentication code that GitHub sent you and choose Verify.

    GitHub two-factor authentication dialog

    Otherwise, the system will automatically recognize your GitHub organization as your GitHub account has previously been associated with your Azure DevOps Services account.

  4. The Add GitHub Repositories dialog automatically displays and selects all GitHub.com repositories for which you are an administrator. Unselect any repositories that you don't want to participate in the integration.

    Confirm your GitHub repositories

    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 details, see Troubleshoot GitHub & Azure Boards integration.

  5. When done, choose Save.

  6. Review the GitHub page that displays and then choose Approve, Install, & Authorize.

    Confirm your GitHub repositories

  7. Provide your GitHub password to confirm.

  8. When done, you should see the new connection with the selected repositories listed.

    GitHub repositories connected

Add a GitHub connection using PAT

We recommend that you use OAuth to connect to your GitHub repository. However, if you need to use a PAT, you can by following these procedures.

Tip

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

  1. To choose a PAT when connecting a GitHub repository, choose plus icon New Connection and then choose the Click here link.

    Ad GitHub repository, choose personal access token

    To create a GitHub PAT, go to GitHub Developer Settings>Personal access tokens.

  2. Enter the PAT and choose Connect.

    Ad GitHub repository, choose personal access token

Register Azure DevOps in GitHub as an OAuth App

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

  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.

    Sign into GitHub Enterprise server

  3. Fill out the form to register your Azure DevOps Server 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:

    http://dev.azure.com/fabrikam/_admin/oauth2/callback

    Register your Azure DevOps Server project

  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.

    Sign into GitHub Enterprise server

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.

    Sign into GitHub Enterprise server

  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.

    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

    Register your Azure DevOps Server project

  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.

    Sign into GitHub Enterprise server

Register your OAuth configuration in Azure DevOps Services

  1. Sign into the web portal for Azure DevOps Services.

  2. Add the GitHub Enterprise Oauth configuration to your organization.

  3. Open Organization settings>Oauth configurations, and choose Add Oauth configuration.

    Organization Settings>OAuth configurations

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

    OAuth configuration dialog

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

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

  2. Choose (1) Project Settings, choose (2) GitHub connections and then (3) Click here to connect to your GitHub Enterprise organization.

    Project Settings>GitHub connections

    Choose from one of the following options—OAuth, Personal Access Token, Username and Password—based on the credentials you've chosen.

    Select authentication method

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

    Tip

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

    Connect using OAuth

    Choose the configuration that you set up in Step 4 of Register your OAuth configuration in Azure DevOps Services, and then choose Connect.

    New GitHub Enterprise connection, OAuth dialog

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

    GitHub sign in dialog

    Connect using a Username and Password

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

    GitHub sign in dialog

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

    New GitHub Enterprise connection, OAuth dialog

Connect Azure DevOps Server to GitHub Enterprise Server

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

  2. Choose (1) Project Settings, choose (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 are choosing to make your connection with those credentials.

    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.

    Connect using OAuth

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

    New GitHub Enterprise connection, OAuth dialog

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

    GitHub sign in dialog

    #### Connect using a Username and Password

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

    GitHub sign in dialog

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

    New GitHub Enterprise connection, OAuth dialog

Add or remove repositories, or remove a connection

  1. To add or remove repositories, open the  actions icon for the connection and choose Add repositories or Remove repositories from the menu.

    Add or remove GitHub repositories

  2. To remove all repositories and the connection, choose the Remove connection option. Then, choose Remove to confirm.

    Confirm remove GitHub connection dialog

Resolve connection issues

See Troubleshoot GitHub repository connection.

Try this next