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-Anforderungsstatus an. Pull-Anforderungsstatus werden in den PR-Workflow integriert und externe Dienste erlauben, sich programmgesteuert bei einer Codeänderung abzumelden, indem einfache Erfolgs-/Fehlertypinformationen einer Pullanforderung zugeordnet werden. Optional können Pullanforderungen blockiert werden, bis der externe Dienst die Änderung genehmigt.

Voraussetzungen

Kategorie	Anforderungen
Projektzugriff	Mitglied eines Projekts.
Erlaubnisse	- Code in privaten Projekten anzeigen: Mindestens einfacher Zugriff. - Klonen oder Mitwirken an Code in privaten Projekten: Mitglied der Sicherheitsgruppe "Mitwirkende" oder entsprechende Berechtigungen im Projekt. – Legen Sie Verzweigungs- oder Repositoryberechtigungen fest: Berechtigungen für die Verzweigung oder das Repository verwalten . - Standardverzweigung ändern: Bearbeiten von Richtlinienberechtigungen für das Repository. - Importieren eines Repositorys: Mitglied der Sicherheitsgruppe "Projektadministratoren " oder "Git-Projektebene Repository erstellen"-Berechtigungssatz auf "Zulassen". Weitere Informationen finden Sie unter Festlegen von Git-Repositoryberechtigungen.
Dienste	Repos aktiviert.
Werkzeuge	Wahlfrei. Verwenden Sie az repos-Befehle : Azure DevOps CLI.

Hinweis

In öffentlichen Projekten haben Benutzer mit Stakeholder-Zugriff vollzugriff auf Azure Repos, einschließlich Anzeigen, Klonen und Beitragen zu Code.

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 statuses und how they can be used to integration in the PR workflow.

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 dieser in der 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).
• Das description Symbol wird neben dem Symbol angezeigt und steht context 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 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.

Hinweis

Wenn die erstellte PR mehr als 100.000 geänderte Dateien enthält, unterstützt diese PR aus Leistungs- und Stabilitätsgründen keine Iterationen. Dies bedeutet, dass alle zusätzlichen Änderungen an dieser PR einbezogen werden, 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 bereitgestellte 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, wenn der Iterationsstatus verwendet wird, sollten die Reset-Bedingungen auf " Zurücksetzen" festgelegt werden, wenn neue Änderungen vorgenommen 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

Allein mithilfe des Status können Die Details von einem externen Dienst den 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 übergeben werden, um die Pullanforderung 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 sind genau wie andere Verzweigungsrichtlinien 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 erst nach der Erstellung der Pullanforderung übergeben, wenn ein succeeded Status bereitgestellt wird. Eine PR kann von der Richtlinie ausgenommen werden, indem sie einen Status von notApplicable, 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 Richtlinie auf oberster Ebene kann standardmäßig angewendet werden, während die PR für anwendbare Richtlinien ausgewertet wird. Da dann zusätzliche bedingte Richtlinien angewendet werden (z. B. basierend auf einer bestimmten Buildausgabe), kann der Status bereitgestellt werden, um sie erforderlich zu machen. Diese Orchestrierungsrichtlinie könnte markiert succeeded werden, wenn sie die Auswertung abgeschlossen hat, oder sie kann markiert notApplicable werden, um auf die PR hinzuweisen, dass die Richtlinie nicht gilt.

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
• Konfigurieren einer Verzweigungsrichtlinie für einen externen Dienst