Connect Azure Boards to GitHub

Azure Boards

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

Azure Boards and GitHub integration is in Public Preview and supported only for Azure DevOps Services at this time.

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 repositories so long as you are an administrator for those repositories.

Add a GitHub connection and repository

  1. Sign into Azure Boards.

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

    Project Settings>Integrations

  3. Enter your GitHub account credentials. Choose an account for which you are an administrator for the repositories you want to connect to.

    GitHub sign in dialog

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

    GitHub two-factor authentication dialog

  5. Review the GitHub authorization dialog that appears which indicates the information you'll allow Azure Boards to access from GitHub. Choose Authorize AzureBoards when ready.

    Project Settings>Integrations

  6. In the Add GitHub repositories dialog, you'll see the list of repositories for which you are an administrator.

    Add GitHub repositories dialog

    Check the ones that you want to add and then choose Save. When done, you should see the new connection with the selected repository listed.

    List of GitHub repositories connected

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.

Add or remove repositories, or remove a connection

  1. To add or remove repositories, open the  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

Use a Personal Access Token (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

Resolve connection issues

See Troubleshoot GitHub repository connection.

Try this next