Créer un serveur d’état de demande de tirage avec Node.js

Article
03/25/2024

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

Le workflow de demande de tirage permet aux développeurs d’obtenir des commentaires sur leur code des pairs ainsi que des outils automatisés. Les outils et services tiers peuvent participer au flux de travail de demande de tirage à l’aide de l’API d’état de la demande de tirage. Cet article vous guide tout au long du processus de création d’un serveur d’état pour valider les demandes de tirage dans un référentiel Git Azure DevOps Services. Pour plus d’informations sur l’état des demandes de tirage, consultez Personnaliser et étendre les flux de travail de demande de tirage avec l’état des demandes de tirage.

Prérequis

Une organisation dans Azure DevOps avec un référentiel Git. Si vous n’avez pas d’organisation, inscrivez-vous pour charger et partager du code dans des référentiels Git privés gratuits illimités.
Installez VS Code ou un autre éditeur de code de votre choix. Les instructions de ce guide utilisent VS Code, mais les étapes d’autres éditeurs de code sont similaires.

Installer Node.js

Pour installer Node.js, téléchargez la version LTS appropriée pour votre plateforme. Le téléchargement contient un programme d’installation, que vous pouvez exécuter pour installer le runtime Node.js sur votre ordinateur local. Lors de l’installation de Node.js, veillez à conserver la partie gestionnaire de package npm de l’installation, qui est sélectionnée par défaut.

Créer un serveur web de base à l’aide d’Express

Les étapes décrites dans cette section utilisent Express, qui est une infrastructure web légère pour Node.js qui fournit un certain nombre de méthodes d’utilitaire HTTP qui simplifient la création d’un serveur web. Cette infrastructure vous fournit les fonctions de base nécessaires pour écouter les événements de demande de tirage.

À partir de la ligne de commande, créez un dossier de projet pour votre serveur web.
```
mkdir pr-server
cd pr-server
```
Utilisez la commande npm init pour créer un nouveau fichier package.json pour le projet.
```
npm init
```
Appuyez sur Entrée pour accepter les valeurs par défaut pour toutes les options, à l’exception du point d’entrée. Remplacez la valeur par app.js.
```
entry point: (index.js) app.js
```
Installez Express dans le répertoire pr-server à l’aide de la commande suivante. Cela installe Express et l’enregistre dans la liste des dépendances.
```
npm install express
```
Créez une application Express simple à générer pour le serveur d’état de demande de tirage. Les étapes suivantes sont basées sur l’exemple Hello World d’Express. Ouvrez le dossier du projet dans VS Code en exécutant la commande suivante à partir du dossier pr-server.
```
code .
```

Créez un fichier (Ctrl + N) et collez-le dans l’exemple de code suivant.

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!')
})

Enregistrez le fichier sous le nom app.js.
Exécutez le serveur web de base à l’aide de la commande suivante :
```
node app.js
```
Vérifiez que le serveur est en cours d’exécution en accédant à http://localhost:3000/.

Écouter les requêtes HTTP POST

Le serveur web va recevoir POST demandes d’Azure DevOps Services. Vous devez donc gérer ces demandes dans votre serveur.

À la fin du fichier app.js, ajoutez le code suivant et enregistrez le fichier.
```
app.post('/', function (req, res) {
    res.send('Received the POST')
})
```
Réexécutez votre serveur web à l’aide de la commande suivante :
```
node app.js
```

Configurer un crochet de service pour les événements de demande de tirage

Les crochets de service sont une fonctionnalité Azure DevOps Services qui peut alerter les services externes lorsque certains événements se produisent. Pour cet exemple, vous souhaiterez configurer deux crochets de service pour les événements de demande de tirage, afin que le serveur d’état puisse être averti. Le premier est destiné à l’événement Demande de tirage créée et le second est destiné à l’événement Demande de tirage mise à jour.

Pour recevoir les notifications de crochet de service, vous devez exposer un port à l’Internet public. L’utilitaire ngrok est très utile pour ce faire dans un environnement de développement.

Téléchargez et décompressez la version ngrok appropriée pour votre plateforme.
Utilisez ngrok pour commencer à écouter sur le même port que votre exemple de serveur - port 3000. Exécutez la commande suivante dans une nouvelle fenêtre de commande.
```
ngrok http 3000
```
Ngrok crée une URL publique qui est transférée vers localhost:3000. Notez que l’URL comme vous en aurez besoin à l’étape suivante. Elle doit ressembler à ceci :
```
http://c3c1bffa.ngrok.io
```
Accédez à votre projet dans Azure DevOps, par exemple https://dev.azure.com/<your account>/<your project name>
Dans le menu de navigation, pointez sur l’engrenage et sélectionnez Crochets de service.
S’il s’agit de votre premier crochet de service, sélectionnez + Créer un abonnement.

Si vous avez déjà configuré d’autres crochets de service, sélectionnez le (+) vert plus pour créer un abonnement de crochet de service.
Dans la boîte de dialogue Nouvel abonnement de crochets de service, sélectionnez Webhooks dans la liste des services, puis sélectionnez Suivant.
Sélectionnez Demande de tirage créée dans la liste des déclencheurs d’événements, puis sélectionnez Suivant.
Dans la page Action, entrez l’URL de ngrok dans la zone URL. Sélectionnez Test pour envoyer un événement de test à votre serveur.

Dans la fenêtre de console ngrok, vous verrez un POST entrant qui a retourné un 200 OK indiquant que votre serveur a reçu l’événement de crochet de service.
```
HTTP Requests
-------------

POST /                         200 OK
```
Dans la fenêtre Notification de test, sélectionnez l’onglet Réponse pour afficher les détails de la réponse à partir de votre serveur. Vous devez voir une longueur de contenu de 17 qui correspond à la longueur de la chaîne de votre gestionnaire POST (par exemple, « Reçu le POST »).
Fermez la fenêtre Notification de test, puis sélectionnez Terminer pour créer le crochet de service.

Passez à nouveau les étapes 3 à 9, mais cette fois configurez l’événement Demande de tirage mise à jour.

Important

Veillez à parcourir les étapes précédentes à deux reprises et à créer des crochets de service pour les événements Demande de tirage créée et Demande de tirage mise à jour.

Publier l’état sur les demandes de tirage

Maintenant que votre serveur peut recevoir des événements de crochet de service lorsque de nouvelles demandes de tirage sont créées, mettez-le à jour pour publier l’état de retour à la demande de tirage.

Les demandes de crochet de service incluent une charge utile JSON décrivant l’événement. Pour aider à analyser le JSON retourné par le crochet de service, installez le package d’analyseur de corps.
```
npm install body-parser
```
Mettez à jour app.js pour utiliser l’analyseur de corps pour l’analyse application/json.
```
var bodyParser = require('body-parser')

app.use(bodyParser.json())
```
Pour simplifier l’exécution d’appels d’API REST à Azure Repos, installez le package azure-devops-node-api.
```
npm install azure-devops-node-api 
```

Mettez à jour app.js pour utiliser le package azure-devops-node-api, configurez les détails d’une connexion à votre compte et obtenez une instance de l’API Git.

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);
    } 
);

Créez une variable d’environnement pour votre URL de collection, en remplaçant <your account> par le nom de votre organisation Azure DevOps.
```
setx COLLECTIONURL "https://dev.azure.com/<your account>"
```
Créez un jeton d’authentification personnel (PAT) pour que votre application utilise les instructions suivantes : Authentification avec des jetons d’accès personnels. Vous devez créer un nouveau PAT pour chaque service que vous utilisez pour accéder à votre compte, en le nommant correctement.
Créez une variable d’environnement pour votre PAT.
```
setx TOKEN "yourtokengoeshere"
```
Mettez à jour la fonction post() pour lire les détails de la demande de tirage à partir de la charge utile du crochet de service. Vous aurez besoin de ces valeurs pour publier l’état de retour.
```
var repoId = req.body.resource.repository.id
var pullRequestId = req.body.resource.pullRequestId
var title = req.body.resource.title
```
Générez l’objet d’état à publier sur la demande de tirage.

State est une énumération de type GitStatusState. Utilisez succeeded pour indiquer que la demande de tirage a passé la vérification de l’état et est prête à être fusionnée.

Le description est une valeur de chaîne qui sera affichée à l’utilisateur dans la section État et le flux d’activité dans la vue détails de la demande de tirage.

Le targetUrl est une URL qui sera utilisée pour créer un lien pour le texte de description dans la section État et le flux d’activité. Il s’agit de l’endroit auquel les utilisateurs peuvent accéder pour obtenir plus d’informations sur l’état, par exemple, un rapport de build ou une exécution de test. Si aucune URL n’est spécifiée, la description s’affiche sous forme de texte sans lien.

Le contexte name et genre sont utilisés pour catégoriser l’état et le distinguer des autres services affichant l’état.
```
    var prStatus = {
        "state": "succeeded",
        "description": "Ready for review",
        "targetUrl": "https://visualstudio.microsoft.com",
        "context": {
            "name": "wip-checker",
            "genre": "continuous-integration"
        }
    }
```
Au lieu de publier aveuglément l’état succeeded, inspectez le titre de demande de tirage pour voir si l’utilisateur a indiqué si la demande de tirage est un travail en cours en ajoutant WIP au titre. Si tel est le cas, remplacez l’état publié par la demande de tirage.
```
    if (title.includes("WIP")) {
        prStatus.state = "pending"
        prStatus.description = "Work in progress"
    }
```
Enfin, publiez l’état à l’aide de la méthode createPullRequestStatus(). Il nécessite l’objet d’état, l’ID de référentiel et l’ID de demande de tirage. Affichez la réponse à la console de nœud afin que vous puissiez voir le résultat du billet.
```
vstsGit.createPullRequestStatus(prStatus, repoId, pullRequestId).then( result => {
    console.log(result)
})
```

La méthode résultante doit ressembler à ceci :

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")
})

Enregistrez app.js et redémarrez votre application de nœud.
```
node app.js
```

Créer une nouvelle demande de tirage pour tester le serveur d’état

Maintenant que votre serveur est en cours d’exécution et écoute des notifications de crochet de service, créez une demande de tirage pour la tester.

Démarrez dans la vue fichiers. Modifiez le fichier readme.md dans votre référentiel (ou tout autre fichier si vous n’avez pas de readme.md).
Apportez une modification et validez les modifications apportées au référentiel.
Veillez à valider les modifications apportées à une nouvelle branche afin de pouvoir créer une demande de tirage à l’étape suivante.
Sélectionnez le lien Créer une demande de tirage.
Ajoutez WIP dans le titre pour tester les fonctionnalités de l’application. Sélectionnez Créer pour créer la demande de tirage.
Une fois la demande de tirage créée, vous verrez la section d’état, avec l’entrée Travail en cours qui lie l’URL spécifiée dans la charge utile.
Mettez à jour le titre de la demande de tirage et supprimez le texte WIP et notez que l’état passe de Travail en cours à Prêt pour la révision.

Étapes suivantes

Dans cet article, vous avez appris les bases de la création d’un service qui écoute les événements de demande de tirage via des crochets de service et peut publier des messages d’état à l’aide de l’API d’état. Pour plus d’informations sur l’API d’état de la demande de tirage, consultez la documentation de l’API REST.
Configurer une stratégie de branche pour un service externe.