Risiconiveaus

Als mensen en hun coding agents honderden pull requests per maand openen, reviewt niemand elke regel. Risiconiveaus leggen de review waar die ertoe doet. Je repository zegt welke paden een laag, gemiddeld of hoog risico hebben. fremforge plaatst het resultaat op elke pull request als de commitstatus fremforge/risk-tier:

Risiconiveaus staan standaard uit. Een eigenaar van de organisatie zet ze aan, eerst in schaduwmodus.

Het beleidsbestand

Voeg .fremforge/risk.yaml toe aan de repository:

version: 1
default: medium        # the tier of a file no rule matches
rules:
  - tier: high
    paths: ["/infra/**", "**/migrations/**", "/.forgejo/workflows/**", "/CODEOWNERS"]
  - tier: low
    paths: ["/docs/**", "*.md"]

Hoe fremforge het leest:

• Vanaf de basisbranch. Het bestand wordt gelezen van de branch waarin de pull request merget, nooit van de pull request zelf, zodat een pull request zijn eigen niveau niet kan verlagen.
• Het hoogste niveau wint. Een bestand krijgt het hoogste niveau van elke regel die erop past, dus db/migrations/README.md hierboven is hoog. Een pull request krijgt het hoogste niveau van al zijn bestanden.
• Hernoemingen tellen met beide namen. infra/main.tf verplaatsen naar docs/main.tf is hoog.
• Het beleid wijzigen is hoog. Een wijziging aan .fremforge/risk.yaml zelf is altijd hoog risico.

Paden zijn globs. * matcht binnen één map, ** over mappen heen, ? één teken. Een glob die met / begint, is verankerd aan de root van de repository. Zonder die / matcht de glob op elk mapniveau, zoals in .gitignore.

Eén beleid voor de hele organisatie

Wil je één beleid gebruiken voor elke repository die geen eigen bestand heeft, zet het dan als .fremforge/risk.yaml in één repository van de organisatie en noem die repository in de instellingen (policy_repo, hieronder). fremforge leest het van de standaardbranch van die repository.

Een beleid controleren voordat je het merget

curl -X POST https://frem.sh/_app/api/v1/orgs/<org>/risk-tier/validate \
  -H "Authorization: Bearer $FREMFORGE_TOKEN" \
  -H "Content-Type: application/json" \
  -d "$(jq -n --rawfile s .fremforge/risk.yaml '{source: $s, paths: ["infra/main.tf", "README.md"]}')"

Het antwoord noemt elke fout, of, met paths, het niveau dat elk pad krijgt en de regel die het bepaalde. Het token heeft policy:read nodig.

Wat hoog risico nodig heeft

Een pull request met hoog risico toont warning op fremforge/risk-tier tot hij beide heeft:

1. Een goedkeuring van een benoemde persoon. Een goedkeurende review op de huidige commit van iemand anders dan de auteur, die op de branch mag goedkeuren. Ze telt voor het account waarmee ze is gegeven: een goedkeuring die je coding agent op jouw verzoek geeft, is jouw goedkeuring. De goedkeuring van een systeembot telt niet. Een latere “request changes” van dezelfde persoon trekt haar in.
2. Een gedragssamenvatting. Een onderdeel in de beschrijving van de pull request met de kop ## Behaviour (of Behavior, Behaviour change, Behaviour summary), met minstens een zin over wat er voor gebruikers of systemen verandert. Dat is wat een reviewer, of iedereen die later de geschiedenis leest, ziet wanneer niemand de diff regel voor regel leest.

Gebruikt je organisatie AI-review met een eigen providersleutel, dan kun je een voltooide AI-review op de commit als samenvatting laten tellen: zet AI-review laten tellen als gedragssamenvatting aan in de instellingen (ai_review_summary). Dat staat standaard uit. Risiconiveaus sturen zelf nooit code ergens heen.

De vrijstelling voor eigenaren van de organisatie. Waar een branchregel de bescherming niet afdwingt voor eigenaren van de organisatie, heeft de eigen pull request van een eigenaar geen goedkeuring nodig, en dat geldt ook voor de pull requests die diens coding agent voor hem opent. Risiconiveaus volgen dezelfde regel en zeggen dat ook: de status luidt “approval waived (org owner …)”. Op een branch zonder enige beschermingsregel vraagt Forgejo van niemand een goedkeuring, dus daar is de eigen pull request van een eigenaar ook vrijgesteld en luidt de status “approval waived (no branch rule)”; die van een lid heeft nog steeds een goedkeuring nodig. De gedragssamenvatting is altijd nodig. Wil je dat wijzigingen met hoog risico van eigenaren door een tweede persoon worden goedgekeurd, vink dan Bescherming ook afdwingen voor eigenaren/beheerders van de organisatie aan op de branchregel.

De status wacht nooit

fremforge/risk-tier is nooit pending. Hij is success of warning, en elke uitkomst is definitief zodra ze is geplaatst:

• Geen beleidsbestand: success, “No risk policy”.
• Een beleid dat niet te parsen is: success, met de melding dat het beleid ongeldig is. Er wordt niets automatisch gemerged.
• Alles wat fremforge niet op tijd kan lezen (20 seconden): success, met de melding dat het niveau niet beschikbaar is en open faalt. Er wordt niets automatisch gemerged.

fremforge plaatst de status binnen enkele seconden nadat een pull request is geopend, er is gepusht, hij is bewerkt, gelabeld of gereviewd. Een job die elke 5 minuten draait, plaatst elke ontbrekende status en kijkt opnieuw naar pull requests met hoog risico die nog wachten.

Bij groepen in de merge queue plaatst fremforge ter informatie het niveau van de hele wijziging van de groep als success. Goedkeuringen worden per pull request gecontroleerd.

fremforge voegt fremforge/risk-tier niet toe aan je branchregels. Vandaag wordt het getoond, niet vereist.

Automatisch mergen bij laag risico

Met de modus on en auto_merge_low: true schakelt fremforge automatisch mergen in op een pull request die aantoonbaar laag risico heeft. Forgejo merget hem dan zodra elke vereiste controle slaagt en aan de goedkeuringen van de branchregel is voldaan. Inschakelen slaat nooit een controle of goedkeuring over.

fremforge schakelt niet in:

• alles wat niet laag is, of een pull request waarvan het geen niveau kon bepalen;
• een concept, of een titel die met WIP begint;
• een pull request met het label risk-tier/no-auto-merge of do-not-merge;
• een pull request die iemand heeft uitgeschakeld, tot er opnieuw naartoe wordt gepusht;
• pull requests van Renovate, die de instellingen voor automatisch mergen van je updates van afhankelijkheden volgen.

Verhoogt een push het niveau van een pull request die fremforge had ingeschakeld, dan trekt fremforge zijn inschakeling in. Een inschakeling die een persoon maakte, trekt het nooit in.

In de console

Eigenaren van de organisatie vinden risiconiveaus onder Bouwen en uitrollen → Active work (https://frem.sh/<org>/_admin/active-work):

• De kaart Risiconiveaus stelt de modus in, automatisch mergen bij laag risico en of AI-review als samenvatting telt. De beleidsrepository van de organisatie stel je in via de API.
• Elke pull request op de pagina toont zijn niveau als badge. Open hem om te zien waarom: het bestand en de regel die het niveau bepaalden, hoeveel bestanden er zijn gewijzigd, en bij hoog risico wie goedkeurde of welke vrijstelling geldt, en waar de gedragssamenvatting vandaan kwam. De pagina toont wat fremforge het laatst voor de pull request heeft geplaatst, dus een pull request verschijnt hier zodra zijn niveau is geplaatst.

Schaduw, aan en uit

Begin een week in schaduwmodus en lees de statussen en de gebeurtenissen would_arm voordat je automatisch mergen aanzet.

curl -X PUT https://frem.sh/_app/api/v1/orgs/<org>/risk-tier/settings \
  -H "Authorization: Bearer $FREMFORGE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"mode": "shadow", "policy_repo": null}'

Het token heeft policy:write nodig; GET op hetzelfde pad vereist policy:read. Elke wijziging wordt geaudit als risk_tier.settings_updated.

Waarom een pull request zijn niveau heeft

curl https://frem.sh/_app/api/v1/orgs/<org>/repos/<repo>/pulls/<number>/risk-tier \
  -H "Authorization: Bearer $FREMFORGE_TOKEN"

Het antwoord geeft de tier, het bestand en de regel die het bepaalden (decided_by), wat een pull request met hoog risico nog needs, wie hem goedkeurde of welke waiver geldt, waar de gedragssamenvatting vandaan kwam, en of hij automatisch zou worden gemerged. Het werkt ook als de modus off is, zodat je een beleid op echte pull requests kunt testen voordat je het aanzet. Het token heeft findings:read nodig, of leestoegang tot de repository. Coding agents krijgen hetzelfde antwoord van de MCP-tool get_pull_request_risk_tier.