Risikostufen

Wenn Menschen und ihre Coding-Agenten Hunderte Pull Requests im Monat öffnen, liest niemand jede Zeile. Risikostufen lenken das Review dorthin, wo es zählt. Dein Repository legt fest, welche Pfade geringes, mittleres oder hohes Risiko haben. fremforge meldet das Ergebnis an jedem Pull Request als Commit-Status fremforge/risk-tier:

Risikostufen sind standardmäßig ausgeschaltet. Ein Owner der Organisation schaltet sie ein, zuerst im Schattenmodus.

Die Richtliniendatei

Füge dem Repository .fremforge/risk.yaml hinzu:

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

So liest fremforge sie:

• Aus dem Ziel-Branch. Die Datei wird aus dem Branch gelesen, in den der Pull Request gemergt wird, nie aus dem Pull Request selbst; ein Pull Request kann seine eigene Stufe also nicht senken.
• Die höchste Stufe gewinnt. Eine Datei bekommt die höchste Stufe aller Regeln, die auf sie passen; db/migrations/README.md ist oben also hoch. Ein Pull Request bekommt die höchste Stufe aller seiner Dateien.
• Umbenennungen zählen mit beiden Namen. infra/main.tf nach docs/main.tf zu verschieben ist hoch.
• Eine Änderung der Richtlinie ist hoch. Eine Änderung an .fremforge/risk.yaml selbst hat immer hohes Risiko.

Pfade sind Glob-Muster. * passt innerhalb eines Verzeichnisses, ** über Verzeichnisse hinweg, ? auf ein Zeichen. Ein Glob, der mit / beginnt, ist an der Wurzel des Repositorys verankert. Ohne / passt er auf jeder Verzeichnisebene, wie in .gitignore.

Eine Richtlinie für die ganze Organisation

Um eine Richtlinie für jedes Repository ohne eigene Datei zu nutzen, leg sie als .fremforge/risk.yaml in einem Repository der Organisation ab und nenne dieses Repository in den Einstellungen (policy_repo, siehe unten). fremforge liest sie aus dem Standard-Branch dieses Repositorys.

Eine Richtlinie vor dem Merge prüfen

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

Die Antwort listet jeden Fehler oder, mit paths, die Stufe jedes Pfads und die Regel, die sie gesetzt hat. Das Token braucht policy:read.

Was hohes Risiko braucht

Ein Pull Request mit hohem Risiko zeigt an fremforge/risk-tier den Status warning, bis er beides hat:

1. Eine Freigabe durch eine benannte Person. Ein zustimmendes Review auf den aktuellen Commit von jemand anderem als dem Autor, der auf dem Branch freigeben darf. Es zählt für das Konto, mit dem es abgegeben wurde: Eine Freigabe, die dein Coding-Agent in deinem Auftrag gibt, ist deine Freigabe. Die Freigabe eines System-Bots zählt nicht. Ein späteres „request changes“ derselben Person zieht sie zurück.
2. Eine Verhaltenszusammenfassung. Ein Abschnitt in der Beschreibung des Pull Requests mit der Überschrift ## Behaviour (oder Behavior, Behaviour change, Behaviour summary) mit mindestens einem Satz dazu, was sich für Nutzer oder Systeme ändert. Das sieht ein Reviewer, oder wer später die Historie liest, wenn niemand den Diff Zeile für Zeile liest.

Nutzt deine Organisation KI-Review mit eigenem Provider-Schlüssel, kannst du ein abgeschlossenes KI-Review auf den Commit als Zusammenfassung zählen lassen: Schalte in den Einstellungen KI-Review als Verhaltenszusammenfassung zählen ein (ai_review_summary). Das ist standardmäßig aus. Risikostufen selbst schicken nie Code irgendwohin.

Die Ausnahme für Owner der Organisation. Wo eine Branch-Regel den Schutz nicht für Owner der Organisation durchsetzt, braucht der eigene Pull Request eines Owners keine Freigabe, und das schließt die Pull Requests ein, die sein Coding-Agent für ihn öffnet. Risikostufen folgen derselben Regel und sagen das: Der Status lautet „approval waived (org owner …)“. Auf einem Branch ganz ohne Schutzregel verlangt Forgejo von niemandem eine Freigabe, daher entfällt sie dort auch für den eigenen Pull Request eines Owners, und der Status lautet „approval waived (no branch rule)“; der eines Mitglieds braucht weiterhin eine Freigabe. Die Verhaltenszusammenfassung ist immer nötig. Damit Änderungen mit hohem Risiko von Ownern durch eine zweite Person freigegeben werden, setze an der Branch-Regel den Haken bei Enforce protection on org owners.

Der Status wartet nie

fremforge/risk-tier ist nie pending. Er ist success oder warning, und jedes Ergebnis ist endgültig, wenn es gemeldet wird:

• Keine Richtliniendatei: success, „No risk policy“.
• Eine Richtlinie, die sich nicht parsen lässt: success, mit dem Hinweis, dass die Richtlinie ungültig ist. Nichts wird automatisch gemergt.
• Alles, was fremforge nicht rechtzeitig lesen kann (20 Sekunden): success, mit dem Hinweis, dass die Stufe nicht verfügbar ist und offen fehlschlägt. Nichts wird automatisch gemergt.

fremforge meldet den Status binnen Sekunden, nachdem ein Pull Request geöffnet, gepusht, bearbeitet, gelabelt oder reviewt wurde. Ein Job alle 5 Minuten meldet fehlende Status nach und schaut erneut auf Pull Requests mit hohem Risiko, die noch warten.

Bei Gruppen der Merge-Queue meldet fremforge die Stufe der gesamten Änderung der Gruppe als success, zur Information. Freigaben werden an jedem einzelnen Pull Request geprüft.

fremforge fügt fremforge/risk-tier nicht zu deinen Branch-Regeln hinzu. Heute wird der Status angezeigt, nicht verlangt.

Auto-Merge bei geringem Risiko

Mit dem Modus on und auto_merge_low: true aktiviert fremforge Auto-Merge für einen Pull Request, der eindeutig geringes Risiko hat. Forgejo mergt ihn dann, sobald jede Pflichtprüfung besteht und die Freigaben der Branch-Regel erfüllt sind. Das Aktivieren überspringt nie eine Prüfung oder Freigabe.

fremforge aktiviert nicht:

• alles, was nicht geringes Risiko hat, oder einen Pull Request, dessen Stufe es nicht bestimmen konnte;
• einen Entwurf oder einen Titel, der mit WIP beginnt;
• einen Pull Request mit dem Label risk-tier/no-auto-merge oder do-not-merge;
• einen Pull Request, bei dem eine Person Auto-Merge deaktiviert hat, bis wieder darauf gepusht wird;
• Renovate-Pull-Requests; die folgen den Auto-Merge-Einstellungen deiner Abhängigkeits-Updates.

Hebt ein Push die Stufe eines Pull Requests, für den fremforge Auto-Merge aktiviert hat, nimmt fremforge die Aktivierung zurück. Eine Aktivierung durch eine Person nimmt es nie zurück.

In der Konsole

Owner der Organisation finden Risikostufen unter Build und Deployment → Active work (https://frem.sh/<org>/_admin/active-work):

• Die Karte Risikostufen legt den Modus fest, Auto-Merge bei geringem Risiko und ob ein KI-Review als Zusammenfassung zählt. Das Richtlinien-Repository der Organisation wird über die API gesetzt.
• Jeder Pull Request auf der Seite zeigt seine Stufe als Badge. Öffne ihn, um den Grund zu sehen: die Datei und Regel, die die Stufe gesetzt haben, wie viele Dateien sich geändert haben und, bei hohem Risiko, wer freigegeben hat oder welche Ausnahme gilt und woher die Verhaltenszusammenfassung stammt. Die Seite zeigt, was fremforge zuletzt für den Pull Request gemeldet hat; ein Pull Request erscheint hier also, sobald seine Stufe gemeldet wurde.

Schatten, an und aus

Starte eine Woche im Schattenmodus und lies die Status und die would_arm-Ereignisse, bevor du Auto-Merge einschaltest.

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

Das Token braucht policy:write; GET auf denselben Pfad braucht policy:read. Jede Änderung wird als risk_tier.settings_updated im Audit-Log erfasst.

Warum ein Pull Request seine Stufe hat

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

Die Antwort nennt die Stufe tier, die Datei und Regel, die sie gesetzt haben (decided_by), was ein Pull Request mit hohem Risiko noch braucht (needs), wer ihn freigegeben hat oder welche Ausnahme (waiver) gilt, woher die Verhaltenszusammenfassung stammt und ob er automatisch gemergt würde. Das funktioniert auch im Modus off, sodass du eine Richtlinie an echten Pull Requests testen kannst, bevor du sie einschaltest. Das Token braucht findings:read oder Lesezugriff auf das Repository. Coding-Agenten bekommen dieselbe Antwort vom MCP-Tool get_pull_request_risk_tier.