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

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

Pull-begäranden är ett bra verktyg för att underlätta kodgranskningar och hantera kodflytt på en lagringsplats. Grenprinciper framtvingar kodkvalitet under pull-begärandeprocessen genom att fastställa krav som måste utföras 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-begäranden. 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.

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

• Status för pull-begäran – är ett sätt för tjänster att associera information om lyckade/misslyckade uppgifter med en pull-begäran.
• Statusprincip – tillhandahåller en mekanism för att blockera slutförande av pull-begäranden tills statusen för pull-begäran indikerar att den har slutförts.
• Anpassade åtgärder – ger 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, , pendingnotSet, , 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?

Låt oss ta en titt 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 skickar bygget kan en status som den här publiceras på PR:

{
    "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 är tillgänglig i en knappbeskrivning.
• När en targetUrl används återges beskrivningen som en länk till URL:en.

Uppdatera status

En tjänst kan uppdatera pr-statusen 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 information, 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. Bokföringsstatus 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.

Kommentar

Om den PR som skapas innehåller mer än 100 000 ändrade filer, stöder den pr av prestanda- och stabilitetsskäl inte iterationer. Det innebär att eventuella ytterligare ändringar av en sådan PR inkluderas, men ingen ny iteration skapas för den ändringen. Dessutom returnerar alla försök att skapa en status för en obefintlig iteration ett fel.

Om statusen som publiceras gäller för hela pr:en, oberoende av koden, kan det däremot 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, om iterationsstatus används, bör återställningsvillkoren anges till Återställ status när det sker 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 för en iteration och en pull-begäran.

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 statusprincipen ett sätt för externa tjänster att blockera slutförande av pr tills kraven uppfylls. Om principen krävs måste den skickas 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 grenprinciper. När du lägger till en ny statusprincip måste statusprincipens namn och genre 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 formatgenrens /namn.

När en statusprincip har angetts kräver det att statusen för med matchningen context av succeeded det valda namnet finns för för att den här principen ska kunna skickas.

Ett behörigt 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

Alternativen för principapplicering avgör om den här principen gäller så snart en pull-begäran har skapats eller om principen tillämpas först efter att den första statusen har publicerats i pull-begäran.

1. Tillämpa som standard – Principen gäller så snart pull-begäran har skapats. Med det här alternativet godkänns inte principen när 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 till pull-begäran.

Tillsammans kan dessa alternativ användas för att skapa en uppsättning dynamiska principer. En "orkestreringsprincip" på den översta nivån kan anges till att gälla som standard medan PR utvärderas för tillämpliga principer. Eftersom ytterligare villkorsprinciper bestäms att tillämpas (kanske baserat på specifika byggutdata) kan statusen sedan publiceras för att göra dem nödvändiga. Den här orkestreringsprincipen kan markeras succeeded när den är klar med utvärderingen eller kan markeras notApplicable för att indikera för PR att principen inte gäller.

Anpassade åtgärder

Förutom fördefinierade tjänstkrokhändelser som kan utlösa tjänsten för att uppdatera PR-status, är det möjligt att utöka statusmenyn med hjälp av Azure DevOps Services-tillägg för att ge utlösaråtgärder till slutanvändaren. Om statusen till exempel motsvarar en testkörning som kan startas om av slutanvändaren är det möjligt att ha menyalternativet Starta om på 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äggsexemplet.

Nästa steg

Läs mer om API:et för PR-status och kolla in guiderna:

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