Personalizzare ed estendere i flussi di lavoro delle richieste pull con lo stato della richiesta pull

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

Le richieste pull sono uno strumento ideale per facilitare le revisioni del codice e la gestione dello spostamento del codice all'interno di un repository. I criteri di ramo applicano la qualità del codice durante il processo di richiesta pull stabilendo i requisiti che devono essere eseguiti per ogni modifica del codice. Questi criteri consentono ai team di applicare molte procedure consigliate correlate alla revisione del codice e all'esecuzione di compilazioni automatizzate, ma molti team hanno requisiti e convalide aggiuntivi da eseguire sul codice. Per soddisfare queste esigenze individuali e personalizzate, Azure Repos offre gli stati delle richieste pull. Gli stati delle richieste pull si integrano nel flusso di lavoro della richiesta pull e consentono ai servizi esterni di disconnettersi a livello di codice tramite l'associazione di informazioni semplici sul tipo di esito positivo/errore a una richiesta pull. Facoltativamente, le richieste pull possono essere bloccate fino a quando il servizio esterno non approva la modifica.

L'integrazione nel flusso di lavoro delle richieste pull prevede alcuni concetti diversi:

• Stato della richiesta pull: consente ai servizi di associare informazioni sull'esito positivo o negativo a una richiesta pull.
• Criteri di stato: fornisce un meccanismo per bloccare il completamento della richiesta pull fino a quando lo stato della richiesta pull non indica l'esito positivo.
• Azioni personalizzate: consente di estendere il menu di stato usando le estensioni di Azure DevOps Services.

In questo argomento verranno fornite informazioni sugli stati delle richieste pull e su come possono essere usati per l'integrazione nel flusso di lavoro delle richieste pull.

Stato della richiesta pull

Lo stato della richiesta pull consente ai servizi di associare semplici informazioni sul tipo di esito positivo/negativo a una richiesta pull tramite l'API Stato. Uno stato è costituito da quattro parti chiave di dati:

• Stato. Uno degli stati predefiniti seguenti: succeeded, failed, pending, notSet, notApplicableo error.
• Descrizione. Stringa che descrive lo stato dell'utente finale.
• Contesto. Nome dello stato, in genere che descrive l'entità che registra lo stato.
• URL. Collegamento in cui gli utenti possono ottenere informazioni più specifiche dello stato.

Essenzialmente, lo stato è il modo in cui un utente o un servizio pubblica la propria valutazione su una richiesta pull e fornisce la risposta a domande come:

• Le modifiche soddisfano i requisiti?
• Dove è possibile ottenere altre informazioni sulle operazioni da eseguire per soddisfare i requisiti?

Di seguito è descritto un esempio. Si consideri un servizio di integrazione continua necessario per compilare tutte le modifiche al codice in un progetto. Quando tale servizio valuta le modifiche in una richiesta pull, deve pubblicare i risultati della compilazione e dei test. Per le modifiche che superano la compilazione, è possibile pubblicare uno stato simile al seguente nella richiesta pull:

{
    "state": "succeeded",
    "description": "CI build succeeded",
    "context": {
        "name": "my-ci-system",
        "genre": "continuous-integration"
    },
    "targetUrl": "http://contoso.com/CI/builds/1"
}

Questo stato verrà visualizzato all'utente finale nella visualizzazione Dettagli richiesta pull:

• L'oggetto state viene visualizzato all'utente usando un'icona (segno di spunta verde per succeeded, x rosso per failed, un orologio per pendinge un rosso ! per error).
• Viene description visualizzato accanto all'icona ed context è disponibile in una descrizione comando.
• Quando un oggetto targetUrl viene applicato, il rendering della descrizione verrà eseguito come collegamento all'URL.

Aggiornamento dello stato

Un servizio può aggiornare lo stato di una richiesta pull per una singola richiesta pull pubblicando stati aggiuntivi, ma solo l'ultima delle quali viene visualizzata per ogni oggetto univoco context. La registrazione di più stati consente agli utenti di gestire le aspettative. Ad esempio, la registrazione di uno pending stato è un buon modo per confermare all'utente che un sistema ha ricevuto un evento e sta avviando il lavoro. L'uso di un'informativa description , ad esempio gli esempi seguenti, può aiutare ulteriormente l'utente a comprendere il funzionamento del sistema:

• "Compilazione in coda"
• "Compilazione in corso"
• "Compilazione riuscita"

Stato dell'iterazione

Quando il ramo di origine in una richiesta pull cambia, viene creata una nuova "iterazione" per tenere traccia delle modifiche più recenti. I servizi che valutano le modifiche del codice dovranno pubblicare nuovo stato in ogni iterazione di una richiesta pull. Lo stato di registrazione a un'iterazione specifica di una richiesta pull garantisce che lo stato si applica solo al codice valutato e nessuno degli aggiornamenti futuri.

Nota

Se la richiesta pull creata contiene più di 100.000 file modificati, per motivi di prestazioni e stabilità, tale richiesta pull non supporterà le iterazioni. Ciò significa che qualsiasi modifica aggiuntiva a tale richiesta pull verrà inclusa, ma non verrà creata alcuna nuova iterazione per tale modifica. Inoltre, qualsiasi tentativo di creare uno stato per un'iterazione inesistente restituirà un errore.

Viceversa, se lo stato pubblicato si applica all'intera richiesta pull, indipendentemente dal codice, la registrazione all'iterazione potrebbe non essere necessaria. Ad esempio, verificare che l'autore (una proprietà pr non modificabile) appartenga a un gruppo specifico debba essere valutato una sola volta e lo stato di iterazione non sarebbe necessario.

Quando si configurano i criteri di stato, se viene usato lo stato di iterazione, le condizioni di reimpostazione devono essere impostate su Reimposta stato ogni volta che sono presenti nuove modifiche. Ciò garantisce inoltre che la richiesta pull non sarà in grado di essere unita fino a quando l'iterazione più recente non ha lo stato .succeeded

Vedere gli esempi dell'API REST per registrare lo stato in un'iterazione e in una richiesta pull.

Criteri di stato

Usando solo lo stato, i dettagli di un servizio esterno possono essere forniti agli utenti all'interno dell'esperienza pull. In alcuni casi, la condivisione di informazioni su una richiesta pull è tutto ciò che è necessario, ma in altri casi le richieste pull devono essere bloccate dall'unione fino a quando non vengono soddisfatti i requisiti. Analogamente ai criteri predefiniti, i criteri di stato consentono ai servizi esterni di bloccare il completamento della richiesta pull fino a quando non vengono soddisfatti i requisiti. Se i criteri sono necessari, è necessario passare per completare la richiesta pull. Se il criterio è facoltativo, è solo informativo e lo stato succeeded di non è necessario per completare la richiesta pull.

I criteri di stato vengono configurati esattamente come gli altri criteri di ramo. Quando si aggiunge un nuovo criterio di stato, è necessario immettere il nome e il genere dei criteri di stato. Se lo stato è stato pubblicato in precedenza, è possibile selezionarlo dall'elenco; se si tratta di un nuovo criterio, è possibile digitare il nome del criterio nel nome del genere/di formato.

Quando si specifica un criterio di stato, è necessario che uno stato di succeeded con il context nome selezionato corrisponda a per poter passare questo criterio.

È anche possibile selezionare un account autorizzato per richiedere che un account specifico disponga dell'autorità per registrare lo stato che approverà i criteri.

Applicabilità dei criteri

Le opzioni di applicabilità dei criteri determinano se questo criterio viene applicato non appena viene creata una richiesta pull o se il criterio viene applicato solo dopo la pubblicazione del primo stato alla richiesta pull.

1. Applica per impostazione predefinita : il criterio viene applicato non appena viene creata la richiesta pull. Con questa opzione, il criterio non passa dopo la creazione della richiesta pull fino a quando non viene pubblicato uno succeeded stato. Una richiesta pull può essere contrassegnata come esente dai criteri pubblicando uno stato di notApplicable, che rimuoverà il requisito del criterio.

2. Condizionale: i criteri non si applicano fino a quando il primo stato non viene inviato alla richiesta pull.

Insieme, queste opzioni possono essere usate per creare una suite di criteri dinamici. Un criterio di "orchestrazione" di primo livello può essere impostato per l'applicazione per impostazione predefinita mentre la richiesta pull viene valutata per i criteri applicabili. Quindi, poiché vengono determinati criteri condizionali aggiuntivi da applicare (ad esempio in base a un output di compilazione specifico), è possibile registrare lo stato per renderli necessari. Questo criterio di orchestrazione può essere contrassegnato succeeded al termine della valutazione o può essere contrassegnato notApplicable per indicare alla richiesta pull che il criterio non è applicabile.

Azioni personalizzate

Oltre agli eventi di hook del servizio predefiniti che possono attivare il servizio per aggiornare lo stato della richiesta pull, è possibile estendere il menu di stato usando le estensioni di Azure DevOps Services per fornire azioni di trigger all'utente finale. Ad esempio, se lo stato corrisponde a un'esecuzione di test che può essere riavviata dall'utente finale, è possibile avere una voce di menu Riavvia al menu di stato che attiverebbe l'esecuzione dei test. Per aggiungere un menu di stato, è necessario usare il modello di contributo. Per altre informazioni, vedere l'esempio di estensione Azure DevOps.

Passaggi successivi

Per altre informazioni sull'API stato della richiesta pull, vedere le guide pratiche:

• Creare un server di stato della richiesta pull con Node.js
• Usare Funzioni di Azure per creare criteri ramo personalizzati
• Configurare un criterio ramo per un servizio esterno