Créer un serveur d’état de pull request avec Node.js

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

Le processus de pull request (PR) permet aux développeurs d’obtenir des commentaires de la part de leurs pairs et des outils automatisés sur leur code. Les outils et services non-Microsoft peuvent participer au workflow PR en utilisant l'API PR Status. 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.

Conditions préalables

Catégorie	Spécifications
Organisation	Une organisation dans Azure DevOps avec un dépôt Git.
Outils	- Visual Studio Code ou un autre éditeur de code de votre choix. - Node.js. 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 du gestionnaire de paquets npm de l’installation, qui est sélectionnée par défaut.
Authentification	Jeton Microsoft Entra ID avec l’étendue Code (status) pour avoir l’autorisation de modifier le statut de la demande de tirage. Pour plus d’informations, consultez Authentification Microsoft Entra.

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 de nombreuses 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 fichier package.json pour le projet.
```
npm init
```
Sélectionnez Entrer pour accepter les valeurs par défaut pour toutes les options, à l’exception du point d’entrée. Remplacez-le 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 sur laquelle vous pourrez vous appuyer pour le serveur d'état PR Les étapes suivantes sont basées sur l’exemple Express Hello World.

a) Ouvrez le dossier du projet dans Visual Studio Code en exécutant la commande suivante à partir du pr-server dossier.
```
code .
```
b. Créez un fichier (Ctrl + N) et collez-le dans l’exemple de code suivant pour créer un serveur Express de base.
```
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!')
})
```
c. Enregistrez le fichier en tant que 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 hooks de service sont une fonctionnalité Azure DevOps Services qui peut alerter les services externes lorsque certains événements se produisent. Pour cet exemple, configurez deux hooks de service pour les événements PR, afin que le serveur d'état puisse être notifié. Le premier concerne l'événement Requête pull créée et le second l'événement Requête pull mise à jour.

Pour recevoir les notifications des hooks de service, exposez un port à l'Internet public. L’utilitaire ngrok est 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 redirige vers localhost:3000. Notez l’URL, car vous en avez besoin à l’étape suivante. Il ressemble à l’exemple suivant :
```
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 hook de service, sélectionnez + Créer un abonnement.

Si vous avez déjà configuré d'autres hooks de service, sélectionnez le signe plus (+) pour créer un nouvel abonnement au hook 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 la console ngrok, un POST entrant renvoie un 200 OK, indiquant que votre serveur a reçu l'événement de service hook.
```
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, « Réception du 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.

Importante

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 analyser 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.getBearerHandler(token)
var connection = new vsts.WebApi(collectionURL, authHandler)
var vstsGit = connection.getGitApi()

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>"
```
Obtenez un jeton Microsoft Entra ID pour utilisation par votre application. Les jetons d’ID Microsoft Entra sont la méthode d’authentification recommandée pour les API REST Azure DevOps. Vous pouvez obtenir ces jetons de différentes manières :
- Option 1 : Azure CLI (pour le développement/test)
```
az account get-access-token --resource 499b84ac-1321-427f-aa17-267ca6975798 --query "accessToken" --output tsv
```
- Option 2 : Principal de service (pour la production)
  1. Inscrire une application dans Microsoft Entra ID
  2. Créer une clé secrète client pour l’application
  3. Accorder les autorisations appropriées à l’application dans Azure DevOps
  4. Utiliser les informations d’identification du principal de service pour obtenir des jetons par programmation
Pour plus d’informations, consultez Authentification Microsoft Entra.
Créez une variable d’environnement pour votre jeton d’ID Microsoft Entra.
```
setx TOKEN "your-entra-id-token-here"
```

Obtention de jetons d’ID Microsoft Entra par programmation (recommandé pour la production)

Pour les applications de production, vous devez obtenir des jetons d’ID Microsoft Entra par programmation plutôt que d’utiliser des jetons statiques. Voici comment implémenter cela à l’aide de la bibliothèque d’authentification Microsoft (MSAL) pour Node.js:

Installez le package MSAL Node :
```
npm install @azure/msal-node
```

Créer un module de fournisseur de jetons (tokenProvider.js) :

const { ConfidentialClientApplication } = require('@azure/msal-node');

const clientConfig = {
    auth: {
        clientId: process.env.CLIENT_ID,
        clientSecret: process.env.CLIENT_SECRET,
        authority: `https://login.microsoftonline.com/${process.env.TENANT_ID}`
    }
};

const cca = new ConfidentialClientApplication(clientConfig);

async function getAccessToken() {
    const clientCredentialRequest = {
        scopes: ['499b84ac-1321-427f-aa17-267ca6975798/.default']
    };

    try {
        const response = await cca.acquireTokenByClientCredential(clientCredentialRequest);
        return response.accessToken;
    } catch (error) {
        console.error('Error acquiring token:', error);
        throw error;
    }
}

module.exports = { getAccessToken };

Mettez à jour votre app.js pour utiliser le fournisseur de jetons :

const { getAccessToken } = require('./tokenProvider');

// Instead of using a static token, get a fresh token
app.post("/", async function (req, res) {
    try {
        const token = await getAccessToken();
        var authHandler = vsts.getBearerHandler(token);
        var connection = new vsts.WebApi(collectionURL, authHandler);

        // ... rest of your POST handler code
    } catch (error) {
        console.error('Authentication error:', error);
        res.status(500).send('Authentication failed');
    }
});

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 avez besoin de ces valeurs pour renvoyer le statut.
```
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 le PR a passé la vérification de statut et peut être fusionné.

Le description est une valeur de chaîne qui s'affiche pour l'utilisateur dans la section Statut et dans le flux d'activité dans la vue Détails du PR.

L'targetUrl est une URL utilisée pour créer un lien pour le texte de description dans la section État et le flux d’activité, c’est-à-dire où 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 apparaît 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 d'afficher immédiatement le statut succeeded, vérifiez le titre de la PR pour voir si l'utilisateur a indiqué que la PR 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 de statut, l'ID du dépôt et l'ID du pull request. Affichez la réponse dans la console Node pour que vous puissiez voir le résultat de la requête.
```
vstsGit.createPullRequestStatus(prStatus, repoId, pullRequestId).then( result => {
    console.log(result)
})
```

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

app.post("/", async function (req, res) {
    try {
        // 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"
        }

        // Get the Git API instance and post the status to the PR
        const gitApi = await vstsGit
        const result = await gitApi.createPullRequestStatus(prStatus, repoId, pullRequestId)
        console.log(result)

        res.send("Received the POST")
    } catch (error) {
        console.error('Error processing PR status:', error)
        res.status(500).send('Error processing request')
    }
})

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

Créez un nouveau PR 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 dépôt (ou tout autre fichier si vous n’avez pas de readme.md).
Apportez une modification et validez les modifications apportées au dépôt.
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 le PR créé, la section d'état s'affiche avec l'entrée Travail en cours qui renvoie à 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.

documentation de l’API REST
Configurer une stratégie de branche pour un service externe

Commentaires

Cette page a-t-elle été utile ?

Last updated on 2025-12-17