Anpassa och utöka arbetsflöden för pull-begäranden med status för pull-begäran

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

Pull-begäranden är ett bra verktyg för att underlätta kodgranskningar och hantera kodflytt på en lagringsplats. Branch-principer tillämpa kodkvalitet under pull request-processen genom att fastställa krav som måste uppfyllas för varje kodändring. Dessa principer gör det möjligt för team att tillämpa många metodtips för att granska kod och köra automatiserade versioner, men många team har ytterligare krav och valideringar att utföra på kod. För att täcka dessa enskilda och anpassade behov erbjuder Azure Repos status för pull-requests. Status för pull-begäranden integreras i PR-arbetsflödet och gör det möjligt för externa tjänster att programmatiskt signera en kodändring genom att associera enkel information av typen lyckad/misslyckad med en pull-begäran. Alternativt kan pull-begäranden blockeras tills den externa tjänsten godkänner ändringen.

Förutsättningar

Integreringen i PR-arbetsflödet omfattar några olika begrepp:

• Pull-begärans status – är ett sätt för tjänster att associera information om lyckande/misslyckande med en pull-begäran.
• Statusprincip – tillhandahåller en mekanism för att blockera slutförande av pull-begäran tills statusen för pull-begäran indikerar att den har slutförts.
• Anpassade åtgärder – är ett sätt att utöka statusmenyn med hjälp av Azure DevOps Services-tillägg.

I det här avsnittet får du lära dig mer om status för pull-begäranden och hur de kan användas för att integrera i PR-arbetsflödet.

Status för pull-begäran

Status för pull-begäran är ett sätt för tjänster att associera enkel information av typen lyckad/misslyckad med en pull-begäran med hjälp av status-API:et. En status består av fyra viktiga datadelar:

• Tillstånd. Något av följande fördefinierade tillstånd: succeeded, failed, pending, notSet, notApplicableeller error.
• Beskrivning. En sträng som beskriver statusen för slutanvändaren.
• Kontext. Ett namn på statusen – som vanligtvis beskriver entiteten som publicerar statusen.
• URL. En länk där användarna kan få mer information som är specifik för statusen.

I huvudsak är status hur en användare eller tjänst publicerar sin utvärdering om en pull-begäran och ger svaret på frågor som:

• Uppfyllde ändringarna kraven?
• Var kan jag lära mig mer om vad jag behöver göra för att uppfylla kraven?

Nu ska vi titta på ett exempel. Överväg en CI-tjänst som krävs för att skapa alla kodändringar i ett projekt. När den tjänsten utvärderar ändringarna i en pull-begäran måste den publicera resultatet av bygget och testerna. För ändringar som klarar bygget kan en status som den här publiceras på pull requesten:

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

Den här statusen visas för slutanvändaren i vyn PR-information:

• state visas för användaren med hjälp av en ikon (grön kontroll för succeeded, rött X för failed, en klocka för pendingoch en röd ! för error).
• description visas bredvid ikonen och context finns i en knappbeskrivning.
• När en targetUrl tillämpas återges beskrivningen som en länk till URL:en.

Uppdaterar status

En tjänst kan uppdatera en PR-status för en enskild PR genom att publicera ytterligare statusar, varav endast den senaste visas för varje unik context. Genom att publicera flera statusar kan användarna hantera förväntningar. Att till exempel publicera en pending status är ett bra sätt att bekräfta för användaren att ett system har tagit emot en händelse och börjar arbeta. Om du använder en informativ description, till exempel följande exempel, kan du ytterligare hjälpa användaren att förstå hur systemet fungerar:

• "Skapa i kö"
• "Bygge pågår"
• "Bygget lyckades"

Iterationsstatus

När källgrenen i en PR ändras skapas en ny "iteration" för att spåra de senaste ändringarna. Tjänster som utvärderar kodändringar vill publicera ny status för varje iteration av en PR. Publiceringsstatus för en specifik iteration av en PR garanterar att status endast gäller för den kod som utvärderades och ingen av de framtida uppdateringarna.

Om statusen som publiceras gäller för hela PR:en, oberoende av koden, kan det vara onödigt att publicera till iterationen. Om du till exempel kontrollerar att författaren (en oföränderlig PR-egenskap) tillhör en viss grupp behöver den bara utvärderas en gång och iterationsstatusen behövs inte.

När du konfigurerar statusprincipen och iterationsstatus används, bör Återställ villkor ställas in till Återställ status när det finns nya ändringar. Detta garanterar ytterligare att PR inte kan sammanfogas förrän den senaste iterationen har statusen succeeded.

Se REST API-exemplen för att publicera status på en iteration och på en pull request.

Statusprincip

Med enbart status kan information från en extern tjänst tillhandahållas till användare i PR-upplevelsen. Ibland är delning av information om en pr allt som är nödvändigt, men i andra fall bör PR blockeras från att slås samman tills kraven uppfylls. Precis som inkorgsprinciperna ger Status-principen ett sätt för externa tjänster att blockera pr-slutförande tills kraven uppfylls. Om policyn krävs måste den godkännas för att slutföra pull-begäran. Om principen är valfri är den endast informationsbaserad och statusen succeeded krävs inte för att slutföra pull-begäran.

Statusprinciper konfigureras precis som andra förgreningsprinciper. När du lägger till en ny statusprincip måste namn och genre för statusprincipen anges. Om statusen har publicerats tidigare kan du välja den från listan. om det är en ny princip kan du skriva in namnet på principen i formatet genre/namn.

När en statusprincip har angetts kräver den att statusen succeeded med context som matchar det valda namnet ska finnas för att den här principen ska kunna gå igenom.

Ett auktoriserat konto kan också väljas för att kräva att ett specifikt konto har behörighet att publicera status som godkänner principen.

Princip tillämplighet

Policy tillämpningsalternativ bestämmer om denna policy gäller så snart en pull-begäran har skapats eller om policyn gäller först efter att den första statusen har publicerats på pull-begäran.

1. Använd som standard – Principen gäller så snart pull-begäran har skapats. Med det här alternativet passerar inte principen efter att pull-begäran har skapats förrän en succeeded-status har publicerats. En PR kan markeras som undantagen från principen genom att publicera statusen notApplicable, vilket tar bort principkravet.

2. Villkorsstyrd – Principen gäller inte förrän den första statusen har publicerats i pull-begäran.

Tillsammans kan dessa alternativ användas för att skapa en uppsättning dynamiska principer. En övergripande orkestreringspolicy kan ställas in som standard medan PR utvärderas för relevanta riktlinjer. När ytterligare villkorsprinciper beslutas att tillämpas (kanske baserat på specifika byggutdata) kan statusen sedan publiceras för att kräva dem. Den här orkestreringsprincipen kan markeras succeeded när den är klar med utvärderingen eller markeras notApplicable för att ange för PR att principen inte gäller.

Anpassade åtgärder

Förutom fördefinierade servicehook-händelser som kan få tjänsten att uppdatera PR-status, är det möjligt att utöka statusmenyn med hjälp av Azure DevOps Services-tillägg som ger slutanvändaren möjlighet att trigga åtgärder. Om statusen till exempel motsvarar en testkörning som kan startas om av slutanvändaren är det möjligt att ha ett Starta om menyalternativ till statusmenyn som utlöser tester som ska köras. Om du vill lägga till en statusmeny måste du använda bidragsmodellen. Mer information finns i Azure DevOps-tilläggsexempel.

Nästa steg

Läs mer om PR Status API och se guiderna:

• Skapa en statusserver för pull-begäran med Node.js
• Använd Azure Functions för att skapa anpassade grenprinciper
• Konfigurera en grenprincip för en extern tjänst