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

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. 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 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 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 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).
• Die description wird neben dem Symbol angezeigt, und der context ist über eine QuickInfo verfügbar.
• 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
• „Buildvorgang wird ausgeführt“
• "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 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 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 außerdem sichergestellt, dass der PR erst dann gemergt werden kann, wenn die neueste Iteration den Status succeeded aufweist.

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 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, 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 von succeeded mit dem context des ausgewählten Namens vorhanden sein, damit diese Richtlinie gilt.

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 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 in die Pullanforderung gepostet wird.

Zusammen können diese Optionen verwendet werden, um eine Reihe dynamischer 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 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