Erstellen eines Pull Request-Statusservers mit Node.js

  • Artikel

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

Der Pull Request (PR)-Workflow bietet Entwicklern die Möglichkeit, Feedback zu ihrem Code von Peers sowie von automatisierten Tools zu erhalten. Tools und Dienste von Drittanbietern können mithilfe der PR-Status-API am PR-Workflow teilnehmen. Dieser Artikel führt Sie durch den Prozess zum Erstellen eines Statusservers, um PRs in einem Azure DevOps Services Git-Repository zu überprüfen. Weitere Informationen zu PR-Status finden Sie unter Anpassen und Erweitern von Pull Request-Workflows mit Pull Request-Status.

Voraussetzungen

  • Eine Organisation in Azure DevOps mit einem Git-Repository. Wenn Sie über keine Organisation verfügen, registrieren Sie sich, um Code in unbegrenzten kostenlosen privaten Git-Repositorys hochzuladen und freizugeben.
  • Installieren Sie VS Code oder einen anderen Code-Editor Ihrer Wahl. Die Anweisungen in diesem Handbuch verwenden VS Code, aber die Schritte in anderen Code-Editoren sind ähnlich.

Installieren von Node.js

Um Node.js zu installieren, laden Sie das für Ihre Plattform geeignete LTS-Release herunter. Der Download enthält ein Installationsprogramm, das Sie ausführen können, um die Node.js Runtime auf Ihrem lokalen Computer zu installieren. Achten Sie bei der Installation von Node.js darauf, den npm-Paket-Manager-Teil der Installation beizubehalten, der standardmäßig ausgewählt ist.

Erstellen eines einfachen Webservers mit Express

Die Schritte in diesem Abschnitt verwenden Express, ein schlankes Webframework für Node.js, das eine Reihe von HTTP-Hilfsprogrammmethoden bereitstellt, die das Erstellen eines Webservers vereinfachen. Dieses Framework bietet ihnen die grundlegenden Funktionen, die zum Lauschen auf PR-Ereignisse erforderlich sind.

  1. Erstellen Sie über die Befehlszeile einen neuen Projektordner für Ihren Webserver.

    mkdir pr-server
cd pr-server

  2. Verwenden Sie den Befehl npm init, um eine neue package.json-Datei für das Projekt zu erstellen.

    npm init

    Drücken Sie die EINGABETASTE, um die Standardwerte für alle Optionen mit Ausnahme des Einstiegspunkts zu übernehmen. Ändern Sie sie in app.js.

    entry point: (index.js) app.js

  3. Installieren Sie Express mit dem folgenden Befehl im Verzeichnis „pr-server“. Dadurch wird Express installiert und in der Abhängigkeitenliste gespeichert.

    npm install express

  4. Erstellen Sie eine einfache Express-App, die für den PR-Statusserver verwendet werden soll. Die folgenden Schritte basieren auf dem Hello World-Beispiel von Express. Öffnen Sie den Projektordner in VS Code, indem Sie den folgenden Befehl im Ordner pr-server ausführen.

    code .

  5. Erstellen Sie eine neue (Ctrl + N)-Datei, und fügen Sie den folgenden Beispielcode in diese ein.

    const express = require('express')
const app = express()

app.get('/', function (req, res) {
res.send('Hello World!')
})

app.listen(3000, function () {
console.log('Example app listening on port 3000!')
})

  6. Speichern Sie die Datei unter dem Namen app.js.

  7. Führen Sie den einfachen Webserver mit dem folgenden Befehl aus:

    node app.js

    Überprüfen Sie, ob der Server ausgeführt wird, indem Sie zu http://localhost:3000/ wechseln.

Lauschen auf HTTP POST-Anforderungen

Der Webserver wird POST-Anforderungen von Azure DevOps Services empfangen, weshalb Sie diese Anforderungen auf Ihrem Server verarbeiten müssen.

  1. Fügen Sie am Ende der app.js-Datei den folgenden Code hinzu, und speichern Sie die Datei.

    app.post('/', function (req, res) {
    res.send('Received the POST')
})

  2. Führen Sie Ihren Webserver mit dem folgenden Befehl erneut aus:

    node app.js

Konfigurieren eines Service Hooks für PR-Ereignisse

Service Hooks sind ein Feature von Azure DevOps Services, das externe Dienste benachrichtigen kann, wenn bestimmte Ereignisse auftreten. In diesem Beispiel sollten Sie zwei Service Hooks für PR-Ereignisse einrichten, damit der Serverserver benachrichtigt werden kann. Der erste ist für das Pull Request erstellt-Ereignis und der zweite für das Pull Request aktualisiert-Ereignis.

Um die Service Hook-Benachrichtigungen zu empfangen, müssen Sie einen Port für das öffentliche Internet verfügbar machen. Das Hilfsprogramm ngrok ist sehr nützlich, um dies in einer Entwicklungsumgebung zu bewerkstelligen.

  1. Laden Sie das entsprechende ngrok-Release für Ihre Plattform herunter, und entzippen Sie es.

  2. Verwenden Sie ngrok, um mit dem Lauschen am selben Port wie Ihr Beispielserver zu beginnen, nämlich Port 3000. Führen Sie in einem Befehlsfenster folgenden Befehl aus.

    ngrok http 3000

    Ngrok erstellt eine öffentliche URL, die an localhost:3000 weiterleitet. Notieren Sie sich diese URL, da Sie sie im nächsten Schritt benötigen. Diese sieht ungefähr so aus:

    http://c3c1bffa.ngrok.io

  3. Navigieren Sie zu Ihrem Projekt in Azure DevOps, z. B. https://dev.azure.com/<your account>/<your project name>.

  4. Zeigen Sie im Navigationsmenü mit dem Mauszeiger auf das Zahnrad, und wählen Sie Service Hooks aus.

    Service Hooks im Administratormenü auswählen

  5. Wenn dies Ihr erster Service Hook ist, wählen Sie + Abonnement erstellen aus.

    „Neues Abonnement erstellen“ auswählen in der Symbolleiste

    Wenn Sie bereits andere Service Hooks konfiguriert haben, wählen Sie das grüne Pluszeichen (+) aus, um ein neues Service Hook-Abonnement zu erstellen.

    Grünes Pluszeichen auswählen, um ein neues Service Hook-Abonnement zu erstellen.

  6. Wählen Sie im Dialogfeld „Neues Service Hook-Abonnement“ die Option Webhooks aus der Liste der Dienste aus, und wählen Sie dann Weiter aus.

    Webhooks aus der Liste der Dienste auswählen

  7. Wählen Sie in der Liste der Ereignistrigger Pull Request erstellt aus, und wählen Sie dann Weiter aus.

    In der Liste der Ereignistrigger „Pull Request erstellt“ auswählen

  8. Geben Sie auf der Seite „Aktion“ die URL von ngrok in das Feld URL ein. Wählen Sie Testen aus, um ein Testereignis an Ihren Server zu senden.

    Die URL eingeben und „Testen“ auswählen, um den Service Hook zu testen

    Im ngrok-Konsolenfenster wird ein eingehender POST angezeigt, der ein 200 OK zurückgegeben hat, was anzeigt, dass Ihr Server das Service Hook-Ereignis empfangen hat.

    HTTP Requests
-------------

POST /                         200 OK

    Wählen Sie im Fenster „Testbenachrichtigung“ die Registerkarte „Antwort“ aus, um die Details der Antwort von Ihrem Server anzuzeigen. Es sollte eine Inhaltslänge von 17 angezeigt werden, was der Länge der Zeichenfolge aus Ihrem POST-Handler entspricht (d. h. „Received the POST“ („POST empfangen“; im Deutschen DE wäre es 14)).

    Registerkarte „Antwort“ auswählen, um die Ergebnisse des Tests anzuzeigen

  9. Schließen Sie das Fenster „Testbenachrichtigung“, und wählen Sie Fertig stellen aus, um den Service Hook zu erstellen.

Führen Sie die Schritte 3 bis 9 erneut aus, aber konfigurieren Sie dieses Mal das Pull Request aktualisiert-Ereignis.

Wichtig

Stellen Sie sicher, dass Sie die vorherigen Schritte zweimal ausführen, und Service Hooks sowohl für das Pull Request erstellt-Ereignis als auch für das Pull Request aktualisiert-Ereignis erstellen.

Bereitstellen des Status in PRs

Nachdem Ihr Server nun Service Hook-Ereignisse empfangen kann, wenn neue PRs erstellt werden, aktualisieren Sie ihn so, dass er den Status an den PR zurückpostet.

  1. Service Hook-Anforderungen enthalten eine JSON-Nutzlast, die das Ereignis beschreibt. Um die vom Service Hook zurückgegebene JSON-Datei zu analysieren, installieren Sie das body-parser-Paket.

    npm install body-parser

  2. Aktualisieren Sie app.js, um „body-parser“ für die Analyse von application/json zu verwenden.

    var bodyParser = require('body-parser')

app.use(bodyParser.json())

  3. Um das Ausführen von REST-API-Aufrufen an Azure Repos zu vereinfachen, installieren Sie das Paket azure-devops-node-api.

    npm install azure-devops-node-api

  4. Aktualisieren Sie app.js, um das Paket „azure-devops-node-api“ zu verwenden, richten Sie die Details für eine Verbindung mit Ihrem Konto ein, und rufen Sie eine Instanz der Git-API ab.

    const vsts = require("azure-devops-node-api")

const collectionURL = process.env.COLLECTIONURL    
const token = process.env.TOKEN

var authHandler = vsts.getPersonalAccessTokenHandler(token)
var connection = new vsts.WebApi(collectionURL, authHandler)

var vstsGit = connection.getGitApi().then( 
    vstsGit => {                                    
        vstsGit.createPullRequestStatus(prStatus, repoId, pullRequestId).then( result => {
            console.log(result);
        },
        error => {
            console.log(error);
        })
    }, 
    error => { 
        console.log(error);
    } 
);

  5. Erstellen Sie eine Umgebungsvariable für Ihre Sammlungs-URL, und ersetzen Sie <your account> durch den Namen Ihrer Azure DevOps-Organisation.

    setx COLLECTIONURL "https://dev.azure.com/<your account>"

  6. Erstellen Sie ein persönliches Authentifizierungstoken (PAT) für Ihre App, und befolgen Sie die folgenden Anweisungen: Authentifizieren mit persönlichen Zugriffstoken. Sie sollten ein neues PAT für jeden Dienst erstellen, den Sie für den Zugriff auf Ihr Konto verwenden, und es entsprechend benennen.

  7. Erstellen Sie eine Umgebungsvariable für Ihr PAT.

    setx TOKEN "yourtokengoeshere"

  8. Aktualisieren Sie die post()-Funktion, um die PR-Details aus der Service Hook-Nutzlast zu lesen. Sie benötigen diese Werte, um den Status zurückzuposten.

    var repoId = req.body.resource.repository.id
var pullRequestId = req.body.resource.pullRequestId
var title = req.body.resource.title

  9. Erstellen Sie das status-Objekt, das in dem PR bereitgestellt werden soll.

    State ist eine Enumeration vom Typ GitStatusState. Verwenden Sie succeeded, um anzuzeigen, dass der PR die Statusüberprüfung bestanden hat und zum Zusammenführen bereit ist.

    description ist ein Zeichenfolgenwert, der dem Benutzer im Abschnitt „Status“ sowie im Aktivitätsfeed in der PR-Detailansicht angezeigt wird.

    Die targetUrl ist eine URL, die verwendet wird, um einen Link für den Beschreibungstext im Abschnitt „Status“ sowie im Aktivitätsfeed zu erstellen. Dies ist die Stelle, wo Benutzer weitere Informationen zum Status abrufen können, z. B. einen Buildbericht oder eine Testausführung. Wenn keine URL angegeben wird, wird die Beschreibung als Text ohne Link angezeigt.

    Die Kontexte name und genre werden verwendet, um den Status zu kategorisieren und von anderen Diensten zu unterscheiden, die einen Status posten.

        var prStatus = {
        "state": "succeeded",
        "description": "Ready for review",
        "targetUrl": "https://visualstudio.microsoft.com",
        "context": {
            "name": "wip-checker",
            "genre": "continuous-integration"
        }
    }

  10. Anstatt nur blind den Status succeeded zu posten, untersuchen Sie den PR-Titel, um festzustellen, ob der Benutzer angezeigt hat, ob sich der PR „In Bearbeitung“ (WIP, Work in Progress) befindet, indem er dem Titel WIP hinzugefügt hat. Wenn ja, ändern Sie den Status, der an den PR zurückgepostet wird.

        if (title.includes("WIP")) {
        prStatus.state = "pending"
        prStatus.description = "Work in progress"
    }

  11. Posten Sie schließlich den Status mithilfe der createPullRequestStatus()-Methode. Hierfür sind das status-Objekt, die Repository-ID und die Pull Request-ID erforderlich. Geben Sie die Antwort an die Knotenkonsole aus, damit Sie das Ergebnis des Posts sehen können.

    vstsGit.createPullRequestStatus(prStatus, repoId, pullRequestId).then( result => {
    console.log(result)
})

  12. Die resultierende Methode sollte in etwa wie folgt aussehen:

    app.post("/", function (req, res) {

    // Get the details about the PR from the service hook payload
    var repoId = req.body.resource.repository.id
    var pullRequestId = req.body.resource.pullRequestId
    var title = req.body.resource.title

    // Build the status object that we want to post.
    // Assume that the PR is ready for review...
    var prStatus = {
        "state": "succeeded",
        "description": "Ready for review",
        "targetUrl": "https://visualstudio.microsoft.com",
        "context": {
            "name": "wip-checker",
            "genre": "continuous-integration"
        }
    }

    // Check the title to see if there is "WIP" in the title.
    if (title.includes("WIP")) {

        // If so, change the status to pending and change the description.
        prStatus.state = "pending"
        prStatus.description = "Work in progress"
    }

    // Post the status to the PR
    vstsGit.createPullRequestStatus(prStatus, repoId, pullRequestId).then( result => {
        console.log(result)
    })

    res.send("Received the POST")
})

  13. Speichern Sie app.js, und starten Sie Ihre Knoten-App neu.

    node app.js

Erstellen eines neuen PR zum Testen des Statusservers

Nachdem Ihr Server nun ausgeführt wird und auf Service Hook-Benachrichtigungen lauscht, erstellen Sie einen Pull Request, um ihn zu testen.

  1. Beginnen Sie in der Dateiansicht. Bearbeiten Sie die „readme.md“-Datei in Ihrem Repository (oder einer anderen Datei, wenn Sie keine „readme.md“ haben).

    „Bearbeiten“ im Kontextmenü auswählen

  2. Nehmen Sie eine Bearbeitung vor, und committen Sie die Änderungen in das Repository.

    Bearbeiten der Datei und Auswählen von „Committen“ in der Symbolleiste

  3. Stellen Sie sicher, dass Sie die Änderungen in einen neuen Branch committen, damit Sie im nächsten Schritt einen PR erstellen können.

    Eingeben eines neuen Branchnamens und Auswählen von „Committen“

  4. Wählen Sie den Link Pull Request erstellen aus.

    Auswählen von „Pull Request erstellen“ auf der Vorschlagsleiste

  5. Fügen Sie dem Titel WIP hinzu, um die Funktionalität der App zu testen. Wählen Sie Erstellen aus, um den PR zu erstellen.

    Hinzufügen von „WIP“ zum PR-Standardtitel

  6. Nachdem der PR erstellt wurde, wird der Abschnitt „Status“ mit dem Eintrag Work in progress (WIP, In Bearbeitung) angezeigt, der mit der in der Nutzlast angegebenen URL verknüpft ist.

    Abschnitt „Status“ mit dem Eintrag „Work in progress“ (WIP, In Bearbeitung).

  7. Aktualisieren Sie den PR-Titel, entfernen Sie den Text WIP, und beachten Sie, dass sich der Status von In Bearbeitung (Work in Progress, WIP) in Bereit für Prüfung ändert.

Nächste Schritte