Anpassen und Erweitern von Pullanforderungsworkflows mit Pullanforderungsstatus

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

Pull-Anforderungen sind ein hervorragendes Tool, um Codeüberprüfungen und die Verwaltung von Codebewegungen innerhalb eines Repositorys zu erleichtern. Verzweigungsrichtlinien erzwingen die Codequalität während des Pullanforderungsprozesses, indem Anforderungen festgelegt werden, die für jede Codeänderung ausgeführt werden müssen. Mit diesen Richtlinien können Teams viele bewährte Methoden im Zusammenhang mit der Überprüfung von Code und das Ausführen automatisierter Builds erzwingen. Viele Teams verfügen jedoch über zusätzliche Anforderungen und Überprüfungen, die sie für Code ausführen müssen. Um diese individuellen und benutzerdefinierten Anforderungen abzudecken, bietet Azure Repos Pull-Request-Status an. Pull-Request-Status werden in den PR-Workflow integriert und ermöglichen es externen Diensten, einer Codeänderung programmgesteuert ihre Genehmigung zu erteilen, indem sie einfache Erfolgs-/Fehlerinformationen mit einem Pull Request verknüpfen. Optional können Pullanforderungen blockiert werden, bis der externe Dienst die Änderung genehmigt.

Voraussetzungen

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

• Pull-Anforderungsstatus – stellt eine Möglichkeit für Dienste bereit, Erfolgs-/Fehlerinformationen einer Pullanforderung zuzuordnen.
• Statusrichtlinie – stellt einen Mechanismus zum Blockieren des Abschlusss der Pullanforderung bereit, bis der Status der Pullanforderung den Erfolg anzeigt.
• Benutzerdefinierte Aktionen – bietet eine Möglichkeit, das Statusmenü mithilfe von Azure DevOps Services-Erweiterungen zu erweitern.

In diesem Thema erfahren Sie mehr über Pull-Request-Status und wie sie im PR-Workflow integriert werden können.

Pullanforderungsstatus

Der Pullanforderungsstatus bietet eine Möglichkeit für Dienste, einfache Erfolgs-/Fehlertypinformationen einer Pullanforderung mithilfe der Status-API zuzuordnen. Ein Status besteht aus vier wichtigen Datenteilen:

• Bundesland. Einer der folgenden vordefinierten Zustände: succeeded, , failed, pending, , notSet, oder notApplicableerror.
• Description. Eine Zeichenfolge, die den Status für den Endbenutzer beschreibt.
• Kontext. Ein Name für den Status – in der Regel, der die Entität beschreibt, die den Status veröffentlicht.
• URL. Ein Link, über den Benutzer spezifischere Informationen für den Status erhalten können.

Im Wesentlichen ist der Status die Art und Weise, wie ein Benutzer oder Dienst seine Bewertung über eine Pull-Anforderung veröffentlicht und die Antwort auf Fragen wie:

• Erfüllten die Änderungen die Anforderungen?
• Wo kann ich mehr darüber erfahren, was ich tun muss, um die Anforderungen zu erfüllen?

Sehen wir uns ein Beispiel an. Erwägen Sie einen CI-Dienst , der zum Erstellen aller Codeänderungen in einem Projekt erforderlich ist. Wenn dieser Dienst die Änderungen in einer Pullanforderung auswertet, muss er die Ergebnisse des Builds und der Tests zurück posten. Bei Änderungen, die den Build erfolgreich bestehen, kann ein Status wie dieser im Pull Request gepostet 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 Endbenutzer in der Ansicht "PR-Details" angezeigt:

• Dies state wird dem Benutzer mit einem Symbol angezeigt (grünes Häkchen für succeeded, rotes X für failed, eine Uhr für pendingund ein rotes ! für error).
• Das description wird neben dem Icon angezeigt, und das context steht in einer QuickInfo zur Verfügung.
• Wenn eine targetUrl Anwendung erfolgt, wird die Beschreibung als Link zur URL gerendert.

Status wird aktualisiert

Ein Dienst kann einen PR-Status für eine einzelne PR aktualisieren, indem zusätzliche Status veröffentlicht werden, von denen nur das neueste für jede eindeutige contextangezeigt wird. Das Veröffentlichen mehrerer Status hilft Benutzern, die Erwartungen zu verwalten. Beispielsweise ist das Posten eines pending Status eine gute Möglichkeit, dem Benutzer zu bestätigen, dass ein System ein Ereignis empfangen hat und die Arbeit startet. Die Verwendung eines informativen description Beispiels wie die folgenden Beispiele kann dem Benutzer weiter helfen zu verstehen, wie das System funktioniert:

• Build steht in der Warteschlange
• "In Bearbeitung erstellen"
• "Build erfolgreich"

Iterationsstatus

Wenn sich der Quellzweig in einer PR ändert, wird eine neue "Iteration" erstellt, um die neuesten Änderungen nachzuverfolgen. Dienste, die Codeänderungen auswerten, möchten bei jeder Iteration einer PR den neuen Status posten. Das Veröffentlichen des Status in einer bestimmten Iteration einer PR garantiert, dass der Status nur für den Code gilt, der ausgewertet wurde, und keines der zukünftigen Updates.

Wenn der veröffentlichte Status hingegen auf die gesamte PR angewendet wird, unabhängig vom Code, kann die Veröffentlichung in der Iteration unnötig sein. Beispielsweise müsste die Überprüfung, ob der Autor (eine unveränderliche PR-Eigenschaft) zu einer bestimmten Gruppe gehört, nur einmal ausgewertet werden, und der Iterationsstatus wäre nicht erforderlich.

Wenn die Statusrichtlinie konfiguriert wird und der Iterationsstatus verwendet wird, sollten die Reset-Bedingungen auf „Status zurücksetzen, wenn neue Änderungen vorgenommen werden“ festgelegt werden. Dadurch wird sichergestellt, dass die PR erst zusammengeführt werden kann, wenn die neueste Iteration über einen Status verfügt succeeded.

Sehen Sie sich die REST-API-Beispiele für die Veröffentlichung des Status einer Iteration und einer Pullanforderung an.

Statusrichtlinie

Mithilfe des Status allein können Details eines externen Dienstes Benutzern innerhalb der PR-Erfahrung zur Verfügung gestellt werden. Manchmal ist das Teilen von Informationen über eine PR alles, was erforderlich ist, aber in anderen Fällen sollten PRs daran gehindert werden, zusammenzuführen, bis die Anforderungen erfüllt sind. Wie bei den vordefinierten Richtlinien bietet die Statusrichtlinie eine Möglichkeit für externe Dienste, den Abschluss der PR zu blockieren, bis die Anforderungen erfüllt sind. Wenn die Richtlinie erforderlich ist, muss sie bestanden werden, um den Pull-Request abzuschließen. Wenn die Richtlinie optional ist, handelt es sich nur um Informationen, und ein Status von succeeded ist nicht erforderlich, um die Pullanforderung abzuschließen.

Statusrichtlinien werden genau wie andere Branchrichtlinien konfiguriert. Beim Hinzufügen einer neuen Statusrichtlinie muss der Name und das Genre der Statusrichtlinie eingegeben werden. Wenn der Status 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 Formatgenrenamen/ eingeben.

Wenn eine Statusrichtlinie angegeben wird, muss ein Status succeeded mit dem context übereinstimmenden Namen vorhanden sein, damit diese Richtlinie übergeben wird.

Ein autorisiertes Konto kann auch ausgewählt werden, um festzulegen, dass ein bestimmtes Konto über die Berechtigung verfügt, den Status zu posten, der die Richtlinie genehmigt.

Anwendbarkeit von Richtlinien

Die Richtlinien anwendbarkeitsoptionen bestimmen, ob diese Richtlinie gilt, sobald eine Pullanforderung erstellt wird, oder ob die Richtlinie nur gilt, nachdem der erste Status in die Pullanforderung gepostet wurde.

1. Standardmäßig übernehmen – Die Richtlinie wird angewendet, sobald die Pullanforderung erstellt wird. Mit dieser Option wird die Richtlinie bei der Erstellung der Pullanforderung nicht genehmigt, bis ein succeeded Status veröffentlicht wird. Eine PR kann von der Richtlinie ausgenommen werden, indem ein Status von notApplicable gepostet wird, der die Richtlinienanforderung entfernt.

2. Bedingt – Die Richtlinie gilt erst, wenn der erste Status in die Pullanforderung gepostet wird.

Zusammen können diese Optionen verwendet werden, um eine Reihe dynamischer Richtlinien zu erstellen. Eine "Orchestrierung"-Richtlinie auf oberster Ebene könnte standardmäßig angewendet werden, während die PR auf anwendbare Richtlinien evaluiert wird. Da zusätzliche bedingte Richtlinien angewendet werden (z. B. basierend auf einer bestimmten Buildausgabe), kann der Status veröffentlicht werden, um sie als erforderlich festzulegen. Diese Orchestrierungsrichtlinie könnte markiert succeeded werden, wenn die Auswertung abgeschlossen ist, oder sie könnte markiert notApplicable werden, um dem PR darzustellen, dass die Richtlinie nicht zutrifft.

Benutzerdefinierte Aktionen

Zusätzlich zu vordefinierten Dienst-Hook-Ereignissen, die den Dienst zum Aktualisieren des PR-Status auslösen können, ist es möglich, das Statusmenü mithilfe von Azure DevOps Services-Erweiterungen zu erweitern, um dem Endbenutzer Triggeraktionen zu gewähren. Wenn der Status z. B. einer Testausführung entspricht, die vom Endbenutzer neu gestartet werden kann, ist es möglich, ein Menüelement " Neustart " in das Statusmenü zu verwenden, das Tests zur Ausführung auslöst. Um ein Statusmenü hinzuzufügen, müssen Sie das Beitragsmodell verwenden. Weitere Informationen finden Sie im Azure DevOps-Erweiterungsbeispiel.

Nächste Schritte

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

• Erstellen eines Pullanforderungsstatusservers mit Node.js
• Verwenden Sie Azure Functions, um benutzerdefinierte Branch Policies zu erstellen
• Eine Verzweigungsrichtlinie für einen externen Dienst konfigurieren