The team "Portal" of Nordlicht Reisen GmbH, a fictional travel agency, works on GitHub, while the team "Betrieb" (German for operations) plans in Azure Boards. The two argue about where the state of the work lives. In addition, the whole company sits in Microsoft Teams and wants to learn there when a pipeline fails, without opening every page one by one. And sales wants an external system to get a message for every new issue.
These are the three skills of this lesson: integrating Azure Boards with GitHub, connecting GitHub or Azure DevOps with Microsoft Teams and setting up webhooks.
Prior knowledge: What AB# and the keywords in pull requests do is covered in lesson 1.1; the map of the two tool worlds in lesson 0.2; accounts and clean-up in lesson 0.1. This lesson shows how the connections are made and operated, not once more what they are for.
Note: All statements come from the documentation of Microsoft Learn and GitHub; the pages are listed under "Further reading". The commands, menu paths and code examples of this lesson were not run; they come from the reference of Microsoft and GitHub.
Connecting Azure Boards to GitHub
The app instead of the individual person
For GitHub.com, Microsoft names the Azure Boards app for GitHub as the recommended way. It authenticates and works as an app instead of as an individual person. That is the advantage over the older ways with OAuth or a personal access token: there, Azure Boards uses the GitHub identity of one individual to watch code activity, and the members of a team change. After the connection, you manage the repositories from Azure Boards or from GitHub.
Prerequisites
| Where | What you need |
|---|---|
| Azure DevOps | Member of the group Project Collection Administrators (whoever created the project has the right); project member in the Azure Boards project |
| GitHub | Administrator or owner of the GitHub organization to install the app; read access to the repository |
| for linking later | Contributor access to the Azure Boards project and the GitHub repository |
Two important notes from the page "Install the Azure Boards app for GitHub":
- If a repository is already connected through another authentication such as OAuth, you must remove it there first before you connect it again through the app.
- You can connect an Azure DevOps organization to several GitHub repositories, provided you are an administrator there. A GitHub repository should not be connected to more than one Azure DevOps organization; otherwise you get unexpected links with
AB#.
Installing and connecting
This is how Microsoft describes the usual flow, starting from GitHub:
- Open the Azure Boards app in the GitHub Marketplace. Under "Plans and pricing", choose the Free plan and Install.
- Under Install & Authorize Azure Boards, choose the repositories you want to connect to Azure Boards (all or selected ones) and Install & Authorize.
- Choose the Azure DevOps organization and the Azure Boards project. Only one project can be connected at a time.
From Azure DevOps, it goes like this:
- Open Project settings, GitHub connections.
- For the first connection, choose Connect your GitHub account and sign in to GitHub; later, New connection. A PAT or GitHub Enterprise Server have their own paths.
- Choose the GitHub account or organization (only those you own or manage appear) and the repositories. The dialog Add GitHub Repositories preselects all repositories in which you are an administrator; remove what should not be connected. Choose Save and confirm on GitHub with Approve, Install, & Authorize.
On the number of repositories: the integration page names for Azure DevOps Services up to 2,000 repository connections per connection; a feature overview in the same documentation reports that the maximum was raised from 500 to 1,000 repositories. Both statements are in the documentation; which one currently applies, you decide on the current page.
Problems and cleaning up the connection
- Empty repository list: The GitHub organization must allow access for third-party apps; under Settings, OAuth app policy of the organization, you grant the Azure Boards app access (you must be an organization owner or administrator). Also check Organization access of the app: if it says Access request pending, choose Grant.
- Changing repositories: In Azure DevOps under Project settings, GitHub connections, in the More options menu of the connection, choose Add repositories or Remove repositories; Remove connection removes all repositories and the connection. If there is a problem, remove the connection and start over.
- Changing access in GitHub: Settings in the profile menu, Integrations, Applications, under Installed GitHub Apps choose Configure for Azure Boards; under Repository access choose All repositories or Only select repositories and save.
What the connection delivers
According to Microsoft, the functions include: linking work items with commits, pull requests, branches and issues; opening linked objects from the board; visibility of pull requests (draft, review status, status of the checks); mentioning pull requests with ! in texts; "Integrated in build" links for YAML pipelines; status badges of Boards in the README file; the release overview with the linked work items; and the synchronization of GitHub issues with work items through a GitHub Action.
The core functions in everyday work:
| Function | How it works |
|---|---|
| Linking | AB#125 in a commit message or in the description of a pull request or issue; in the title or in a comment of a pull request it has no effect |
| Changing the state | Fixes AB#123 or Closed AB#123; it only takes effect on merging into the default branch |
| Mentioning pull requests | type ! in a text field or comment of a work item and choose the pull request from the list of connected repositories |
| Branch from the work item | Work item actions, New GitHub branch, choose name, repository and base branch, Create |
| Linking by hand | in the work item under Development, Add link, choose the link type and the repository |
| Visibility of pull requests | in GitHub, for the Azure Boards app, accept the changed permissions for reading and writing checks |
| Integrated in build | in the YAML pipeline, More actions, Settings, Automatically link new work items in this build |
Microsoft describes a side effect when you link a pull request by hand: Azure Boards can automatically add a badge to the README file of the first repository in the connection list, create a commit for it and open a pull request for that change. The badge does not appear if the linked pull request is already merged. Expect this in an exercise.
With Azure DevOps Server, the integration only works with GitHub Enterprise Server; there, a sync job fetches the GitHub events hourly, so the links appear with a delay.