Das Team „Portal“ der Nordlicht Reisen GmbH arbeitet bei GitHub, das Team „Betrieb“ plant in Azure Boards. Beide streiten, wo der Stand der Arbeit steht. Außerdem sitzt die ganze Firma in Microsoft Teams und will dort erfahren, wenn eine Pipeline scheitert, ohne jede Seite einzeln zu öffnen. Und der Vertrieb möchte, dass ein externes System bei jedem neuen Issue eine Nachricht bekommt.
Das sind die drei Fähigkeiten dieser Lektion: Azure Boards mit GitHub integrieren, GitHub oder Azure DevOps mit Microsoft Teams verbinden und Webhooks einrichten.
Vorwissen: Was AB# und die Schlüsselwörter in Pull Requests bewirken, steht in Lektion 1.1; die Landkarte der beiden Werkzeugwelten in Lektion 0.2; Konten und Aufräumen in Lektion 0.1. Diese Lektion zeigt, wie die Verbindungen hergestellt und betrieben werden, nicht noch einmal, wozu sie dienen.
Hinweis: Alle Angaben stammen aus der Dokumentation von Microsoft Learn und GitHub; die Seiten stehen unter „Weiterlesen“. Die Befehle, Menüpfade und Codebeispiele dieser Lektion wurden nicht ausgeführt; sie stammen aus der Referenz von Microsoft und GitHub.
Azure Boards mit GitHub verbinden
Die App statt der Einzelperson
Microsoft nennt für GitHub.com die Azure Boards App für GitHub als den empfohlenen Weg. Sie authentifiziert und arbeitet als App statt als eine einzelne Person. Das ist der Vorteil gegenüber den älteren Wegen mit OAuth oder einem persönlichen Zugriffstoken: Dort nutzt Azure Boards die GitHub-Identität eines Einzelnen, um Code-Aktivität zu beobachten, und die Mitglieder eines Teams wechseln. Nach der Verbindung verwalten Sie die Repositories von Azure Boards oder von GitHub aus.
Voraussetzungen
| Wo | Was Sie brauchen |
|---|---|
| Azure DevOps | Mitglied der Gruppe Project Collection Administrators (wer das Projekt angelegt hat, hat das Recht); Projektmitglied im Azure-Boards-Projekt |
| GitHub | Administrator oder Besitzer der GitHub-Organisation, um die App zu installieren; Lesezugriff auf das Repository |
| zum Verknüpfen später | Contributor-Zugriff auf das Azure-Boards-Projekt und das GitHub-Repository |
Zwei wichtige Hinweise der Seite „Install the Azure Boards app for GitHub“:
- Ist ein Repository bereits über eine andere Authentifizierung wie OAuth verbunden, müssen Sie es dort zuerst entfernen, bevor Sie es über die App neu verbinden.
- Sie können eine Azure-DevOps-Organisation mit mehreren GitHub-Repositories verbinden, sofern Sie dort Administrator sind. Ein GitHub-Repository sollte nicht mit mehr als einer Azure-DevOps-Organisation verbunden werden; sonst kommt es zu unerwarteten Verknüpfungen mit
AB#.
Installieren und verbinden
So beschreibt Microsoft den üblichen Ablauf, von GitHub aus:
- Öffnen Sie die App Azure Boards im GitHub Marketplace. Wählen Sie unter „Plans and pricing“ den Tarif Free und Install.
- Wählen Sie unter Install & Authorize Azure Boards die Repositories, die Sie mit Azure Boards verbinden wollen (alle oder ausgewählte), und Install & Authorize.
- Wählen Sie die Azure-DevOps-Organisation und das Azure-Boards-Projekt. Es lässt sich immer nur ein Projekt zur Zeit verbinden.
Von Azure DevOps aus geht es so:
- Öffnen Sie Project settings, GitHub connections.
- Wählen Sie bei der ersten Verbindung Connect your GitHub account und melden Sie sich bei GitHub an; später New connection. Mit einem PAT oder für GitHub Enterprise Server gibt es eigene Wege.
- Wählen Sie das GitHub-Konto oder die Organisation (es erscheinen nur solche, die Sie besitzen oder verwalten) und die Repositories. Das Dialogfeld Add GitHub Repositories wählt alle Repositories vor, in denen Sie Administrator sind; entfernen Sie, was nicht verbunden werden soll. Wählen Sie Save und bestätigen Sie auf GitHub mit Approve, Install, & Authorize.
Zur Zahl der Repositories: Die Seite zur Integration nennt für Azure DevOps Services bis zu 2.000 Repository-Verbindungen je Verbindung; eine Funktionsübersicht derselben Dokumentation berichtet, das Maximum sei von 500 auf 1.000 Repositories angehoben worden. Beide Angaben stehen in der Dokumentation; welche gerade gilt, entscheiden Sie auf der aktuellen Seite.
Probleme und Aufräumen der Verbindung
- Leere Repository-Liste: Die GitHub-Organisation muss den Zugriff von Drittanbieter-Apps erlauben; unter Settings, OAuth app policy der Organisation gewähren Sie der App Azure Boards den Zugriff (Sie müssen Organisationsinhaber oder -administrator sein). Prüfen Sie auch Organization access der App: Steht dort Access request pending, wählen Sie Grant.
- Repositories ändern: In Azure DevOps unter Project settings, GitHub connections im Menü More options der Verbindung Add repositories oder Remove repositories; Remove connection entfernt alle Repositories und die Verbindung. Bei einem Problem entfernen Sie die Verbindung und beginnen neu.
- Zugriff in GitHub ändern: Settings im Profilmenü, Integrations, Applications, unter Installed GitHub Apps bei Azure Boards Configure; unter Repository access wählen Sie All repositories oder Only select repositories und speichern.
Was die Verbindung liefert
Zu den Funktionen zählen laut Microsoft: Arbeitselemente mit Commits, Pull Requests, Branches und Issues verknüpfen; verknüpfte Objekte vom Board aus öffnen; Einblick in Pull Requests (Entwurf, Prüfstatus, Status der Prüfungen); Pull Requests mit ! in Texten erwähnen; für YAML-Pipelines „Integrated in build“-Verknüpfungen; Statusabzeichen von Boards in der README-Datei; die Release-Übersicht mit den verknüpften Arbeitselementen; und die Synchronisierung von GitHub Issues mit Arbeitselementen über eine GitHub Action.
Die Kernfunktionen im Alltag:
| Funktion | So geht es |
|---|---|
| Verknüpfen | AB#125 in Commit-Nachricht oder Beschreibung eines Pull Requests oder Issues; im Titel oder im Kommentar eines Pull Requests wirkt es nicht |
| Zustand wechseln | Fixes AB#123 oder Closed AB#123; wirkt nur beim Zusammenführen in den Standardbranch |
| Pull Requests erwähnen | in einem Textfeld oder Kommentar eines Arbeitselements ! tippen und den Pull Request aus der Liste der verbundenen Repositories wählen |
| Branch aus dem Arbeitselement | Work item actions, New GitHub branch, Namen, Repository und Basisbranch wählen, Create |
| Verknüpfung von Hand | im Arbeitselement unter Development Add link, Verknüpfungsart und Repository wählen |
| Einblick in Pull Requests | in GitHub bei der App Azure Boards die geänderten Berechtigungen für Lesen und Schreiben von Checks annehmen |
| Integrated in build | in der YAML-Pipeline More actions, Settings, Automatically link new work items in this build |
Eine Nebenwirkung beschreibt Microsoft beim Verknüpfen eines Pull Requests von Hand: Azure Boards kann automatisch ein Abzeichen in die README-Datei des ersten Repositorys der Verbindungsliste eintragen, einen Commit dafür erzeugen und einen Pull Request für diese Änderung anlegen. Das Abzeichen erscheint nicht, wenn der verlinkte Pull Request schon zusammengeführt ist. Rechnen Sie in einer Übung damit.
Bei Azure DevOps Server funktioniert die Integration nur mit GitHub Enterprise Server; dort holt ein Abgleich die GitHub-Ereignisse stündlich ab, die Verknüpfungen erscheinen verzögert.