Risknivåer

När personer och deras kodagenter öppnar hundratals pull requests i månaden granskar ingen varje rad. Risknivåer lägger granskningen där den gör nytta. Ditt repo anger vilka sökvägar som har låg, medel eller hög risk. fremforge publicerar resultatet på varje pull request som commit-statusen fremforge/risk-tier:

Risknivåer är avstängda som standard. En organisationsägare slår på dem, först i skuggläge.

Policyfilen

Lägg till .fremforge/risk.yaml i repot:

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"]

Så här läser fremforge den:

• Från målbranchen. Filen läses från den branch som pull requesten mergas in i, aldrig från själva pull requesten, så en pull request kan inte sänka sin egen nivå.
• Den högsta nivån vinner. En fil får den högsta nivån bland alla regler som matchar den, så db/migrations/README.md ovan har hög risk. En pull request får den högsta nivån bland alla sina filer.
• Namnbyten räknas med båda namnen. Att flytta infra/main.tf till docs/main.tf har hög risk.
• Att ändra policyn har hög risk. En ändring av själva .fremforge/risk.yaml har alltid hög risk.

Sökvägar är globmönster. * matchar inom en katalog, ** över kataloger, ? ett tecken. Ett globmönster som börjar med / är förankrat i repots rot. Utan det matchar mönstret på vilken katalognivå som helst, som i .gitignore.

En policy för hela organisationen

Om du vill använda en policy för alla repon som saknar en egen fil lägger du den som .fremforge/risk.yaml i ett av organisationens repon och anger det repot i inställningarna (policy_repo, nedan). fremforge läser den från det repots standardbranch.

Kontrollera en policy innan du mergar den

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"]}')"

Svaret listar alla fel, eller med paths den nivå varje sökväg får och den regel som satte den. Token behöver policy:read.

Vad hög risk kräver

En pull request med hög risk visar warning på fremforge/risk-tier tills den har båda:

1. Ett godkännande från en namngiven person. En godkännande granskning av den aktuella commiten från någon annan än författaren, som får godkänna på branchen. Den räknas efter det konto den gavs från: ett godkännande som din kodagent ger på din begäran är ditt godkännande. Ett godkännande från en systembot räknas inte. En senare “request changes” från samma person drar tillbaka det.
2. En beteendesammanfattning. Ett avsnitt i pull requestens beskrivning med rubriken ## Behaviour (eller Behavior, Behaviour change, Behaviour summary), med minst en mening om vad som ändras för användare eller system. Det är vad en granskare, eller den som läser historiken senare, ser när ingen läser diffen rad för rad.

Om din organisation använder AI-granskning med en egen leverantörsnyckel kan du låta en slutförd AI-granskning av commiten räknas som sammanfattningen: slå på Räkna AI-granskning som beteendesammanfattning i inställningarna (ai_review_summary). Den är avstängd som standard. Risknivåer skickar aldrig själva kod någonstans.

Undantaget för organisationsägare. Där en branch-regel inte tillämpar skyddet på organisationens ägare behöver en organisationsägares egen pull request inget godkännande, och det gäller även de pull requests som ägarens kodagent öppnar åt hen. Risknivåer följer samma regel och säger det: statusen lyder “approval waived (org owner …)”. På en branch helt utan skyddsregel kräver Forgejo inget godkännande av någon, så även där undantas en ägares egen pull request och statusen lyder “approval waived (no branch rule)”; en medlems pull request behöver fortfarande ett godkännande. Beteendesammanfattningen krävs alltid. Om du vill att ägares ändringar med hög risk ska godkännas av en andra person kryssar du i Tillämpa skyddet även för organisationens ägare/administratörer på branch-regeln.

Statusen väntar aldrig

fremforge/risk-tier är aldrig pending. Den är success eller warning, och varje utfall är slutgiltigt när det publiceras:

• Ingen policyfil: success, “No risk policy”.
• En policy som inte kan tolkas: success, med beskedet att policyn är ogiltig. Inget mergas automatiskt.
• Allt som fremforge inte kan läsa i tid (20 sekunder): success, med beskedet att nivån inte är tillgänglig och att kontrollen släpper igenom. Inget mergas automatiskt.

fremforge publicerar statusen inom några sekunder efter att en pull request har öppnats, fått en push, redigerats, fått en etikett eller granskats. Ett jobb var 5:e minut publicerar statusar som saknas och tittar igen på pull requests med hög risk som fortfarande väntar.

För grupper i merge-kön publicerar fremforge nivån för gruppens hela ändring som success, i informationssyfte. Godkännanden kontrolleras på varje pull request.

fremforge lägger inte till fremforge/risk-tier i dina branch-regler. I dag visas den, men den krävs inte.

Automatisk merge vid låg risk

Med läget on och auto_merge_low: true förbereder fremforge automatisk merge av en pull request som uttryckligen har låg risk. Forgejo mergar den sedan när alla obligatoriska kontroller går igenom och branch-regelns godkännanden är uppfyllda. Förberedelsen hoppar aldrig över en kontroll eller ett godkännande.

fremforge förbereder inte:

• något som inte har låg risk, eller en pull request som det inte kunde bedöma;
• ett utkast, eller en titel som börjar med WIP;
• en pull request med etiketten risk-tier/no-auto-merge eller do-not-merge;
• en pull request där en person har stängt av automatisk merge, förrän den får en ny push;
• Renovate-pull requests, som följer inställningarna för automatisk merge i beroendeuppdateringar.

Om en push höjer nivån för en pull request som fremforge har förberett avbryter fremforge sin förberedelse. Det avbryter aldrig en automatisk merge som en person har satt upp.

I konsolen

Organisationens ägare hittar risknivåer under Bygg och driftsätt → Active work (https://frem.sh/<org>/_admin/active-work):

• Kortet Risknivåer anger läget, automatisk merge vid låg risk och om AI-granskning räknas som sammanfattningen. Organisationens policyrepository anges via API:t.
• Varje pull request på sidan visar sin nivå som en bricka. Öppna den för att se varför: filen och regeln som satte nivån, hur många filer som ändrades och, vid hög risk, vem som godkände eller vilket undantag som gäller, och var beteendesammanfattningen kom ifrån. Sidan visar det som fremforge senast publicerade för pull requesten, så en pull request visas här först när dess nivå har publicerats.

Skuggläge, på och av

Börja i skuggläge i en vecka och läs statusarna och would_arm-händelserna innan du slår på automatisk merge.

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}'

Token behöver policy:write; GET på samma sökväg behöver policy:read. Varje ändring granskningsloggas som risk_tier.settings_updated.

Varför en pull request har sin nivå

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

Svaret anger tier, filen och regeln som satte den (decided_by), vad en pull request med hög risk fortfarande behöver (needs), vem som godkände den eller vilket undantag (waiver) som gäller, var beteendesammanfattningen kom ifrån och om den skulle mergas automatiskt. Det fungerar även när läget är off, så du kan testa en policy på riktiga pull requests innan du slår på den. Token behöver findings:read, eller läsåtkomst till repot. Kodagenter får samma svar från MCP-verktyget get_pull_request_risk_tier.