Creare un server di stato della richiesta pull con Node.js

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

Il flusso di lavoro della richiesta pull offre agli sviluppatori l'opportunità di ottenere commenti e suggerimenti sul codice dai peer e dagli strumenti automatizzati. Gli strumenti e i servizi non Microsoft possono partecipare al flusso di lavoro delle richieste pull usando l'API di stato della richiesta pull. Questo articolo illustra il processo di creazione di un server di stato per convalidare le pull request in un repository Git di Azure DevOps Services. Per ulteriori informazioni sullo stato delle richieste di pull, consultare Personalizzare ed estendere i flussi di lavoro delle richieste di pull con lo stato delle richieste di pull.

Prerequisiti

• Un'organizzazione in Azure DevOps con un repository Git. Se non hai un'organizzazione, iscriviti per caricare e condividere codice in repository Git privati gratuiti e illimitati.
• Installare VS Code o un altro editor di codice preferito. Le istruzioni in questa guida usano VS Code, ma i passaggi in altri editor di codice sono simili.

Installare Node.js

Per installare Node.js, scaricare la versione LTS appropriata per la piattaforma. Il download contiene un programma di installazione, che è possibile eseguire per installare il runtime Node.js nel computer locale. Quando si installa Node.js, assicurarsi di mantenere la parte di installazione per il gestore di pacchetti npm , che è selezionata per impostazione predefinita.

Creare un server Web di base con Express

I passaggi di questa sezione usano Express, che è un framework Web leggero per Node.js che fornisce molti metodi di utilità HTTP che semplificano la creazione di un server Web. Questo framework fornisce le funzionalità di base necessarie per ascoltare gli eventi di pull request.

1. Dalla riga di comando creare una nuova cartella di progetto per il server Web.

   mkdir pr-server
   cd pr-server
   

2. Usare il comando npm init per creare un nuovo file di package.json per il progetto.

   npm init
   

   Selezionare Immettere per accettare le impostazioni predefinite per tutte le opzioni, ad eccezione del punto di ingresso. Modificarlo in app.js

   entry point: (index.js) app.js
   

3. Installare Express nella directory pr-server usando il comando seguente. Viene installato Express e salvato nell'elenco delle dipendenze.

   npm install express
   

4. Creare un'app Express come base per il server di stato di avanzamento della PR. I passaggi seguenti si basano sull'esempio express Hello world. Aprire la cartella del progetto in VS Code eseguendo il comando seguente dalla cartella pr-server.

   code .
   

5. Creare un nuovo file (Ctrl + N) e incollarlo nel codice di esempio seguente.

   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. Salvare il file come app.js.

7. Eseguire il server Web di base usando il comando seguente:

   node app.js
   

   Verificare che il server sia in esecuzione navigando su http://localhost:3000/.

Ascolto delle richieste HTTP POST

Il server Web riceverà POST richieste da Azure DevOps Services, quindi è necessario gestire tali richieste nel server.

1. Alla fine del file app.js aggiungere il codice seguente e salvare il file.

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

2. Riavviare il server web usando il comando seguente:

   node app.js
   

Configura un hook di servizio per eventi PR

Gli hook del servizio sono una funzionalità di Azure DevOps Services che può avvisare i servizi esterni quando si verificano determinati eventi. Per questo esempio, configurare due ganci di servizio per gli eventi di pull request, in modo che il server di stato possa ricevere una notifica. Il primo è per l'evento creato della richiesta pull e il secondo è per l'evento aggiornato della richiesta pull .

Per ricevere le notifiche dei service hook, esporre una porta su Internet pubblica. L'utilità ngrok è utile per farlo in un ambiente di sviluppo.

1. Scaricare e decomprimere la versione ngrok appropriata per la piattaforma.

2. Usare ngrok per avviare l'ascolto sulla stessa porta del server di esempio- porta 3000. Eseguire il comando seguente in una nuova finestra di comando.

   ngrok http 3000
   

   Ngrok crea un URL pubblico che viene inoltrato a localhost:3000. Prendere nota dell'URL, come necessario nel passaggio successivo. L'esempio seguente è simile al seguente:

   http://c3c1bffa.ngrok.io
   

3. Passa al tuo progetto in Azure DevOps. Ecco un esempio: https://dev.azure.com/<your account>/<your project name>

4. Dal menu di navigazione, passare il puntatore del mouse sull'icona dell'ingranaggio e selezionare Service Hooks.

   

5. Se questo è il tuo primo hook del servizio, seleziona + Crea sottoscrizione.

   

   Se hai già configurato altri hook di servizio, seleziona il segno più (+) per creare una nuova sottoscrizione per gli hook di servizio.

   

6. Nella finestra di dialogo Nuova sottoscrizione hook del servizio selezionare Web Hooks dall'elenco dei servizi, quindi selezionare Avanti.

   

7. Selezionare richiesta pull creata dall'elenco dei trigger di eventi e quindi selezionare Avanti.

   

8. Nella pagina Azione, immettere l'URL da ngrok nella casella URL. Selezionare Test per inviare un evento di test al server.

   

   Nella finestra della console di ngrok un POST ricevuto restituisce un 200 OK, indicando che il server ha ricevuto l'evento del service hook.

   HTTP Requests
   -------------
   
   POST /                         200 OK
   

   Nella finestra Notifica test selezionare la scheda Risposta per visualizzare i dettagli della risposta dal server. Dovrebbe essere visualizzata una lunghezza del contenuto pari a 17 che corrisponde alla lunghezza della stringa del gestore POST, ad esempio "Received the POST".

   

9. Chiudere la finestra della notifica di test e selezionare Fine per creare l'hook di servizio.

Eseguire nuovamente i passaggi da 3 a 9, ma questa volta configurare l'evento pull request aggiornata.

Importante

Assicurarsi di eseguire due volte i passaggi precedenti e creare hook del servizio per gli eventi di creazione della richiesta pull e aggiornamento della richiesta pull .

Aggiornare lo stato delle PR

Ora che il server può ricevere eventi di hook del servizio quando vengono create nuove richieste pull, aggiorna il server per inviare indietro lo stato alla richiesta pull.

1. Le richieste di hook del servizio includono un payload JSON che descrive l'evento. Per analizzare il JSON restituito dall'hook del servizio, installare il pacchetto body-parser .

   npm install body-parser
   

2. Aggiorna app.js per usare body-parser per analizzare application/json.

   var bodyParser = require('body-parser')
   
   app.use(bodyParser.json())
   

3. Per semplificare l'esecuzione di chiamate API REST ad Azure Repos, installare il pacchetto azure-devops-node-api.

   npm install azure-devops-node-api 
   

4. Aggiornare app.js per usare il pacchetto azure-devops-node-api, configurare i dettagli per una connessione all'account e ottenere un'istanza dell'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);
       } 
   );
   

5. Creare una variabile di ambiente per l'URL della raccolta, sostituendo <your account> con il nome dell'organizzazione Azure DevOps.

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

6. Creare un token di autenticazione personale da utilizzare nella tua app, seguendo queste istruzioni: Autenticazione con token di accesso personali. È consigliabile creare un nuovo pat per ogni servizio usato per accedere all'account, assegnandogli un nome appropriato.

7. Creare una variabile di ambiente per il PAT.

   setx TOKEN "yourtokengoeshere"
   

8. Aggiornare la funzione post() per leggere i dettagli del PR dal payload dell'hook del servizio. Sono necessari questi valori per il ripristino dello stato.

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

9. Costruire l'oggetto stato da pubblicare nella pull request.

   State è un'enumerazione di tipo GitStatusState. Usare succeeded per indicare che la pull request ha superato l'ispezione dello stato ed è pronta per essere unita.

   Il description è un valore stringa che viene visualizzato all'utente nella sezione Stato e nel feed attività nella visualizzazione dei dettagli della richiesta pull.

   Il targetUrl è un URL usato per creare un collegamento per il testo della descrizione nella sezione Stato e nel feed attività, dove gli utenti possono accedere per ottenere altre informazioni sullo stato, ad esempio un report di compilazione o un'esecuzione di test. Se non viene specificato alcun URL, la descrizione viene visualizzata come testo senza collegamento.

   Il contesto name e genre vengono usati per classificare lo stato e distinguerlo dallo stato di registrazione di altri servizi.

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

10. Invece di pubblicare immediatamente lo stato di succeeded, controlla il titolo della pull request per verificare se l'utente ha indicato che la pull request è un lavoro in progresso aggiungendo WIP al titolo. In tal caso, modificare lo stato inviato nuovamente alla richiesta pull.

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

11. Infine, pubblicare lo stato usando il metodo createPullRequestStatus(). Richiede l'oggetto di stato, l'ID del repository e l'ID della pull request. Restituire la risposta alla console del nodo in modo da visualizzare il risultato del post.

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

12. Il metodo risultante dovrebbe essere simile al seguente:

    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. Salvare app.js e riavviare l'app node.

    node app.js
    

Creare una nuova richiesta pull per testare il server di stato

Ora che il server è in esecuzione e in ascolto delle notifiche di hook di servizio, effettua una pull request per verificarlo.

1. Inizia nella vista file. Modificare il file readme.md nel repository (o qualsiasi altro file se non si dispone di un readme.md).

   

2. Apportare una modifica ed eseguire il commit delle modifiche nel repository.

   

3. Assicurati di eseguire il commit delle modifiche in un nuovo branch in modo da poter creare una PR nel passaggio successivo.

   

4. Seleziona il collegamento Crea un pull request.

   

5. Aggiungere WIP nel titolo per verificare la funzionalità dell'app. Selezionare Crea per creare la richiesta pull.

   

6. Una volta che la richiesta pull è stata creata, la sezione dello stato viene visualizzata con la voce Lavoro in corso che collega all'URL specificato nel payload.

   

7. Aggiornare il titolo del pull request e rimuovere il testo WIP e notare che lo stato cambia da In lavorazione a Pronto per la revisione.

Articoli correlati

• documentazione dell'API REST
• Configurare un criterio di filiale per un servizio esterno