Anpassen und Erweitern von Pull Request-Workflows mit dem Pull Request-Status

Azure DevOps Services | Azure DevOps Server 2022 | Azure DevOps Server 2019

Pull Requests sind ein hervorragendes Tool, um Code Reviews zu vereinfachen und Codeverschiebungen innerhalb eines Repositorys zu verwalten. Branchrichtlinien erzwingen die Codequalität während des Pull Request-Prozesses, indem sie Anforderungen festlegen, die bei jeder Codeänderung erfüllt werden müssen. Mit diesen Richtlinien können Teams viele bewährte Methoden für die Überprüfung von Code und das Ausführen automatischer Builds erzwingen, aber für viele Teams müssen zusätzliche Anforderungen an den Code gestellt und Überprüfungen durchgeführt werden. Um diese individuellen und benutzerdefinierten Anforderungen abzudecken, bietet Azure Repos Pull Request-Statusangaben an. Pull Request-Statusangaben sind in den PR-Workflow integriert und ermöglichen es externen Diensten, eine Codeänderung programmgesteuert abzuzeichnen, indem sie einem Pull Request einfache Informationen zum Erfolg/Misserfolg zuordnen. Optional können Pull Requests blockiert werden, bis der externe Dienst die Änderung genehmigt hat.

Die Integration in den PR-Workflow umfasst einige verschiedene Konzepte:

• Pull Request-Status – Bietet eine Möglichkeit für Dienste, einem Pull Request Informationen zum Erfolg/Misserfolg zuzuordnen.
• Statusrichtlinie – Bietet einen Mechanismus, um den Pull Request-Abschluss zu blockieren, bis der Pull Request-Status auf einen Erfolg hinweist.
• Benutzerdefinierte Aktionen – Bietet eine Möglichkeit, das Statusmenü mithilfe von Azure DevOps Services-Erweiterungen zu erweitern.

In diesem Thema erhalten Sie Informationen zu Pull Request-Statusangaben und wie Sie diese für die Integration in den PR-Workflow verwenden können.

Pull Request-Status

Der Pull Request-Status ermöglicht es Diensten, mithilfe der Status-API einem Pull Request einfache Informationen zum Erfolg/Misserfolg zuzuordnen. Ein Status besteht aus vier wichtigen Datenkomponenten:

• Zustand Einer der folgenden vordefinierten Zustände: succeeded, failed, pending, notSet, notApplicable oder error.
• Beschreibung. Eine Zeichenfolge, die den Status für den Benutzer beschreibt.
• Kontext. Eine Bezeichnung für den Status, in der Regel eine Beschreibung der Entität, die den Status veröffentlicht.
• URL. Ein Link, über den Benutzer weitere Informationen zu diesem Status abrufen können.

Im Wesentlichen ist der Status die Art und Weise, wie ein Benutzer oder Dienst seine Pull Request-Auswertung veröffentlicht und die Antwort auf Fragen wie die folgenden bereitstellt:

• Haben die Änderungen den Anforderungen entsprochen?
• Wo kann ich mehr darüber erfahren, wie ich vorgehen muss, um die Anforderungen zu erfüllen?

Schauen wir uns ein Beispiel an. Betrachten Sie einen CI-Dienst, der zum Erstellen aller Codeänderungen in einem Projekt erforderlich ist. Wenn dieser Dienst die Änderungen in einem Pull Request auswertet, muss er die Ergebnisse des Builds und der Tests zurückgeben. Bei Änderungen, die den Build bestehen, kann ein Status wie der folgende im PR veröffentlicht werden:

{
    "state": "succeeded",
    "description": "CI build succeeded",
    "context": {
        "name": "my-ci-system",
        "genre": "continuous-integration"
    },
    "targetUrl": "http://contoso.com/CI/builds/1"
}

Dieser Status wird dem Benutzer in der Ansicht „PR-Details“ angezeigt:

• Der state wird dem Benutzer mithilfe eines Symbols angezeigt (grüner Haken für succeeded, rotes X für failed, eine Uhr für pending und ein rotes ! für error).
• Die description wird neben dem Symbol angezeigt, und der context ist über eine QuickInfo verfügbar.
• Wenn eine targetUrl angewendet wird, erfolgt das Rendern der Beschreibung als Link zur URL.

Status „Wird aktualisiert“

Ein Dienst kann einen PR-Status für einen einzelnen PR aktualisieren, indem er zusätzliche Statusangaben veröffentlicht, von denen nur die letzte für jeden eindeutigen context angezeigt wird. Das Veröffentlichen mehrerer Statusangaben hilft Benutzern beim Verwalten der Erwartungen. Das Senden eines pending-Status ist z. B. eine gute Möglichkeit, dem Benutzer zu bestätigen, dass ein System ein Ereignis erhalten hat und mit der Arbeit beginnt. Wenn Sie eine informative description wie die folgenden Beispiele verwenden, kann der Benutzer besser verstehen, wie das System funktioniert:

• „Buildvorgang in die Warteschlange gestellt“
• „Buildvorgang wird ausgeführt“
• „Buildvorgang erfolgreich“

Iterationsstatus

Wenn sich der Quellbranch in einem PR ändert, wird eine neue „Iteration“ erstellt, um die letzten Änderungen nachzuverfolgen. Dienste, die Codeänderungen auswerten, möchten bei jeder Iteration eines PR einen neuen Status veröffentlichen. Wenn Sie den Status für eine bestimmte Iteration eines PR veröffentlichen, wird sichergestellt, dass dieser Status nur für den ausgewerteten Code und nicht für zukünftige Aktualisierungen gilt.

Hinweis

Wenn der zu erstellende PR mehr als 100.000 geänderte Dateien enthält, unterstützt dieser PR aus Leistungs- und Stabilitätsgründen keine Iterationen. Das bedeutet, dass alle zusätzlichen Änderungen an diesem PR enthalten sind, aber keine neue Iteration für diese Änderung erstellt wird. Darüber hinaus gibt jeder Versuch, einen Status für eine nicht vorhandene Iteration zu erstellen, einen Fehler zurück.

Wenn der veröffentlichte Status hingegen für den gesamten PR gilt, unabhängig vom Code, kann das Veröffentlichen für die Iteration unnötig sein. Beispielsweise müsste die Überprüfung, ob der Ersteller (eine unveränderliche PR-Eigenschaft) zu einer bestimmten Gruppe gehört, nur einmal ausgewertet werden, und der Iterationsstatus wäre nicht erforderlich.

Wenn bei der Konfiguration der Statusrichtlinie der Iterationsstatus verwendet wird, sollten die Zurücksetzungsbedingungen auf Status bei neuen Änderungen zurücksetzen festgelegt werden. Dadurch wird außerdem sichergestellt, dass der PR erst dann gemergt werden kann, wenn die neueste Iteration den Status succeeded aufweist.

Informationen zum Veröffentlichen von Statusangaben für eine Iteration und für einen Pull Request finden Sie in den Beispielen zur REST-API.

Statusrichtlinie

Allein mithilfe des Status können die Details von einem externen Dienst den Benutzern innerhalb der PR-Umgebung zur Verfügung gestellt werden. Manchmal reicht es aus, Informationen zu einem PR freizugeben, aber in anderen Fällen sollte die Zusammenführung von PRs blockiert werden, bis die Anforderungen erfüllt sind. Wie die Eingangsrichtlinien bietet auch die Statusrichtlinie eine Möglichkeit für externe Dienste, den PR-Abschluss zu blockieren, bis die Anforderungen erfüllt sind. Wenn die Richtlinie erforderlich ist, muss sie eingehalten werden, damit der Pull Request abgeschlossen werden kann. Wenn die Richtlinie optional ist, hat sie nur informativen Charakter, und ein Status von succeeded ist nicht erforderlich, um den Pull Request abzuschließen.

Statusrichtlinien werden genau wie andere Branchrichtlinien konfiguriert. Wenn Sie eine neue Statusrichtlinie hinzufügen, müssen Sie den Namen und das Genre der Statusrichtlinie eingeben. Wenn der Status bereits zuvor veröffentlicht wurde, können Sie ihn aus der Liste auswählen. Wenn es sich um eine neue Richtlinie handelt, können Sie den Namen der Richtlinie im Format Genre/Name eingeben.

Wenn eine Statusrichtlinie angegeben wird, muss ein Status von succeeded mit dem context des ausgewählten Namens vorhanden sein, damit diese Richtlinie gilt.

Ein autorisiertes Konto kann auch ausgewählt werden, um zu erfordern, dass ein bestimmtes Konto über die Befugnis verfügt, den Status zu veröffentlichen, der die Richtlinie genehmigt.

Anwendbarkeit von Richtlinien

Die Optionen der Anwendbarkeit von Richtlinien legen fest, ob diese Richtlinie gilt, sobald ein Pull Request erstellt wird, oder ob die Richtlinie erst gilt, nachdem der erste Status für den Pull Request veröffentlicht wurde.

1. Standardmäßig anwenden: Die Richtlinie gilt, sobald der Pull Request erstellt wurde. Mit dieser Option gilt die Richtlinie nach der Erstellung von Pull Requests nicht, bis ein succeeded-Status vorhanden ist. Ein PR kann als von der Richtlinie ausgenommen markiert werden, indem er den Status notApplicable veröffentlicht. Damit wird die Anforderung der Richtlinie entfernt.

2. Bedingt: Die Richtlinie gilt erst, wenn der erste Status für den Pull Request veröffentlicht wird.

Zusammen können diese Optionen verwendet werden, um eine Sammlung von dynamischen Richtlinien zu erstellen. Eine „Orchestrierungsrichtlinie“ auf oberster Ebene könnte so festgelegt werden, dass sie standardmäßig angewendet wird, während der PR auf anwendbare Richtlinien ausgewertet wird. Wenn dann zusätzliche bedingte Richtlinien zur Anwendung kommen (vielleicht auf der Grundlage bestimmter Buildausgaben), kann der Status so veröffentlicht werden, dass sie erforderlich sind. Diese Orchestrierungsrichtlinie könnte mit succeeded markiert werden, wenn sie fertig ausgewertet ist, oder mit notApplicable, um dem PR zu signalisieren, dass die Richtlinie nicht gilt.

Benutzerdefinierte Aktionen

Zusätzlich zu den vordefinierten Service Hook-Ereignissen, die den Dienst zur Aktualisierung des PR-Status auslösen können, ist es möglich, das Statusmenü mithilfe von Azure DevOps Services-Erweiterungen zu erweitern, damit Endbenutzer*innen Triggeraktionen nutzen können. Wenn z. B. der Status einem Testlauf entspricht, der von Benutzer*innen neu gestartet werden kann, ist es möglich, ein Menüelement Neustart zum Statusmenü hinzuzufügen, das die Ausführung von Tests auslöst. Um ein Statusmenü hinzuzufügen, müssen Sie das Beitragsmodell verwenden. Weitere Informationen finden Sie im Beispiel der Azure DevOps-Erweiterung.

Nächste Schritte

Erfahren Sie mehr über die PR-Status-API und sehen Sie sich die Schrittanleitungen an:

• Erstellen eines Pull Request-Statusservers mit Node.js
• Verwenden von Azure Functions zum Erstellen benutzerdefinierter Branchrichtlinien
• Konfigurieren einer Branch-Richtlinie für einen externen Dienst