Pull requests worden toegepast in veel code repositories. Dit zorgt ervoor dat code niet zonder controle (door collega’s of een automatische validatie) gemerged kan worden met de “main” branch van de repository. In dit blog leggen we je uit hoe je in slechts 5 simpele stappen een geautomatiseerde pipeline kan maken welke je comments in je pull request plaatst. Deze comments zorgen ervoor dat er veel minder fouten aanwezig zijn bij het mergen van de code, bijvoorbeeld door automatisch tips te geven om de code te verbeteren.
Kwaliteit waarborgen
Hierdoor waarborg je de kwaliteit van elke pull request (PR) die door je team worden gemaakt doordat simpele weg meer ogen je code hebben gezien. Het zal zorgen voor minder fouten bij het mergen van code wat zorgt voor minder bugs in productie.
Dit bereik je door een combinatie van de volgende functies in Azure DevOps (AZDO):
- Geautomatiseerde required pipelines die controleren op vereisten zoals unit test pass rate.
- Pull request description templates om ervoor te zorgen dat ontwikkelaars taken afvinken zoals het toevoegen van tests voordat ze de PR maken.
- Approval gates zoals het toevoegen van vereiste reviewers en het blokkeren van force push vanuit Git.
Vele mogelijkheden door REST API van Azure DevOps
Maar wist je dat je nog veel meer dat je kunt doen als je de REST API van AZDO gebruikt? In dit blog wordt de API gebruikt voor het automatiseren van comments in een PR. We zullen tevens de volgende regels toevoegen aan onze PRs:
- Sta niet toe dat een PR wordt voltooid voordat je required pipelines zijn gedraaid. Deze pipelines kunnen dus bijvoorbeeld comments op de PR plaatsen.
- Sta niet toe dat een PR wordt gemerged als er nog onopgeloste comments zijn.
Door automatisch comments toe te voegen aan PRs kun je:
- Een gedetailleerde geschiedenis van de PR bijhouden door een samenvatting van (mislukte) pipelines als comments toe te voegen, inclusief mogelijke stappen om de problemen op te lossen. Dit is een simpeler overzicht dan wanneer de hele pipeline geopend moet worden om fouten te onderzoeken.
- Handmatige stappen beschrijven die moeten worden ondernomen voordat een PR kan worden voltooid, zoals het aanmaken van een firewall regel in een ander project. Soms kan zoiets niet geautomatiseerd worden, waardoor de comment dient als een nuttige herinnering.
- Markeer waarschuwingen die op lange termijn problemen kunnen opleveren, zoals specifieke problemen in de code.
Zo zijn er nog veel meer creatieve mogelijkheden; vooral als je deze aanpak combineert met andere AZDO API endpoints. Denk bijvoorbeeld aan het aanmaken van een backlog item wanneer iets fout gaat in de pipeline.
In 5 stappen een automatische comment pipeline
In 5 simpele stappen gaan we nu de automatische comment pipeline toevoegen. We nemen als voorbeeld een DevOps project. We maken de pipeline aan, geven de build agent de juiste rechten en laten een voorbeeld zien over hoe je de comment kan linken aan code van de repository.
Stap 1: Maak een pipeline voor het toevoegen van een comment
Begin je pipeline door onderstaande template toe te voegen aan de repository. Hierdoor kun je geautomatiseerd comments aan PRs toevoegen.
trigger: none
pool:
vmImage: "ubuntu-latest"
steps:
- task: PowerShell@2
displayName: Post comment on Pull Request
env:
SYSTEM_ACCESSTOKEN: $(System.AccessToken)
inputs:
targetType: inline
pwsh: true
script: |
# Several environment variables are injected from the build agent run
# Note the System.AccessToken, which can be used for all sorts of automation using the AZDO API
$baseUrl = "$($env:SYSTEM_TEAMFOUNDATIONCOLLECTIONURI)$($env:SYSTEM_TEAMPROJECTID)/_apis/git/repositories/$($env:BUILD_REPOSITORY_NAME)/pullRequests/$($env:SYSTEM_PULLREQUEST_PULLREQUESTID)"
$authHeader = @{ Authorization = "Bearer $($env:SYSTEM_ACCESSTOKEN)"}
$threadUrl = "$($baseUrl)/threads?api-version=6.0"
# AZDO supports Markdown, so feel free to edit this multiline comment as you see fit
$commentMarkdown = @'
Test comment, please resolve the following *foobar issues*...
'@
$body = @{
comments = @(
@{
parentCommentId = 0
content = $commentMarkdown
commentType = 1
}
)
status = "active"
}
$body = ConvertTo-Json $body
Write-Host $body
# Simply invoke the AZDO REST API using a POST request!
Invoke-RestMethod -Uri $threadUrl -Method POST -Headers $authHeader -Body $body -ContentType application/json
Stap 2: Voeg comment resolution en build validation toe aan je main/trunk branch
Schakel zowel comments resolution als build validation in voor de main/trunk branch binnen je AZDO Project Instellingen. Zorg ervoor dat de build validation de eerder aangemaakte comments PR pipeline gebruikt.
Stap 3: Zorg ervoor dat de build pipeline rechten heeft om PR comments toe te voegen
Deze stap is belangrijk, maar gemakkelijk te vergeten! De access token die de pipeline zal ophalen van de build agent kan gebruikt worden om de AZDO API te queryen, maar deze token heeft standaard niet veel permissies! Zorg ervoor dat onder Project Settings > Repositories de gebruiker YOUR_PROJECT_NAME Build Service te vinden is. Sta (expliciet) de `Contribute to pull request` permissie toe voor alle of specifieke repositories. Controleer dubbel dat je dit toepast op de juiste gebruiker; andere groepen/gebruikers zullen waarschijnlijk niet werken!
Troubleshooting
Als je Git acties in je pipeline uitvoert kan het voorkomen dat je tegen onderstaande foutmelding aanloopt. In deze foutmelding mist de pipeline rechten om een nieuwe PR comment thread aan te maken. Check opnieuw dat de juiste build pipeline service de correcte permissies heeft zoals bovenstaand beschreven staan.
{“$id”:”1",”innerException”:null,”message”:”TF401027: You need the Git ‘PullRequestContribute’ permission to perform this action. Details: identity ‘Build\\0758a548-dc3b-4c2e-95be-8e2ef6888f4c’, scope ‘repository’.”,”typeName”:”Microsoft.TeamFoundation.Git.Server.GitNeedsPermissionException, Microsoft.TeamFoundation.Git.Server”,”typeKey”:”GitNeedsPermissionException”,”errorCode”:0,”eventId”:3000}
Stap 4: Push een test commit naar een andere branch dan main, en maak een PR!
Zodra je een nieuwe PR aanmaakt, zal de validatie pipeline onmiddellijk draaien. In ons voorbeeld stuurt de pipeline altijd een comment. Omdat je alle comments moet oplossen om een PR samen te voegen, blokkeert je comment de merge totdat het probleem wat de comment aanduidt wordt opgelost door jou of een collega.
Stap 5: Geavanceerde comments
Hoe het toevoegen van comments een krachtig hulpmiddel kan zijn, laten we je graag zien met nog een extra voorbeeld. Dit voorbeeld voegt zelfs een inline code comment toe:
# Replace the $body parameter from the first example with this one
$body = @{
comments = @(
@{
content = $commentMarkdown
commentType = 1
}
)
status = "active"
threadContext = @{
# This determines the file for which the comment will be placed
# Replace this with your pipeline path for a quick test
filePath = "/PATHTOYOURPIPELINE.yml"
# leftFile is the newest version of the file shown in AZDO in the side-by-side view
leftFileStart = @{
line = 1
offset = 1
}
leftFileEnd = @{
line = 2
offset = 1
}
}
}Bezoek de Pull Request API documentatie om andere opties te verkennen. Vergeet niet, je kan jouw build agent permissies geven om ook andere AZDO API endpoints te queryen!
Conclusie
Kortom, het proces om de pipeline automatisch comments achter te laten op een pull request kan een stuk simpeler. Het vereist alleen een goed gedefinieerde pipeline en de juiste rechten voor de agent die de pipeline draait. Zo worden er door het automatisch toevoegen van comments een hoop mogelijkheden gecreëerd om de kwaliteit van de PRs te verhogen.
We hopen – door het relatief simpele voorbeeld uit dit blog – je inspiratie te hebben gegeven voor jouw eigen scenario. Heb je bijvoorbeeld al gedacht aan een pipeline die code scant voor credentials die je per ongeluk in de code hebt staan? In plaats van dat deze pipeline faalt en de gevonden credentials in tekstvorm beschrijft in een pipeline log, zou deze pipeline ook inline code comments in de PR kunnen zetten, die direct wijzen naar de regels code waar de credentials in staan. Zo wordt ook voor reviewers het probleem extra duidelijk. De comments zouden na het oplossen van het probleem zelfs door de pipeline zelf gesloten kunnen worden, zodat de PR kan worden gemerged zonder extra handmatige acties.
Wij zijn benieuwd naar jullie oplossingen, tips & tricks. Waar gebruiken jullie (geautomatiseerde) comments voor bij pull requests?
