Niveaux de risque

Lorsque des personnes et leurs agents de code ouvrent des centaines de pull requests par mois, personne ne relit chaque ligne. Les niveaux de risque concentrent la revue là où elle compte. Votre dépôt indique quels chemins présentent un risque faible, moyen ou élevé. fremforge publie le résultat sur chaque pull request sous forme de statut de commit fremforge/risk-tier :

Les niveaux de risque sont désactivés par défaut. Un propriétaire de l’organisation les active, d’abord en mode fantôme.

Le fichier de politique

Ajoutez .fremforge/risk.yaml au dépôt :

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

Comment fremforge le lit :

• Depuis la branche de base. Le fichier est lu sur la branche dans laquelle la pull request fusionne, jamais dans la pull request elle-même : une pull request ne peut donc pas abaisser son propre niveau.
• Le niveau le plus élevé l’emporte. Un fichier reçoit le niveau le plus élevé parmi toutes les règles qui lui correspondent : db/migrations/README.md ci-dessus est donc high. Une pull request reçoit le niveau le plus élevé de tous ses fichiers.
• Les renommages comptent sous les deux noms. Déplacer infra/main.tf vers docs/main.tf est high.
• Modifier la politique est à risque élevé. Une modification de .fremforge/risk.yaml lui-même est toujours à risque élevé.

Les chemins sont des globs. * correspond à l’intérieur d’un répertoire, ** à travers les répertoires, ? à un caractère. Un glob qui commence par / est ancré à la racine du dépôt. Sans cela, le glob correspond à n’importe quel niveau de répertoire, comme dans .gitignore.

Une seule politique pour toute l’organisation

Pour utiliser une seule politique dans chaque dépôt qui n’a pas son propre fichier, conservez-la sous .fremforge/risk.yaml dans un dépôt de l’organisation et désignez ce dépôt dans les paramètres (policy_repo, ci-dessous). fremforge la lit sur la branche par défaut de ce dépôt.

Vérifier une politique avant de la fusionner

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

La réponse liste chaque erreur ou, avec paths, le niveau attribué à chaque chemin et la règle qui l’a fixé. Le jeton doit avoir policy:read.

Ce qu’exige le risque élevé

Une pull request à risque élevé affiche warning sur fremforge/risk-tier tant qu’elle n’a pas les deux éléments suivants :

1. L’approbation d’une personne nommée. Une revue d’approbation sur le commit actuel, par une autre personne que l’auteur, habilitée à approuver sur la branche. Elle compte selon le compte sous lequel elle a été donnée : une approbation que votre agent de code donne à votre demande est votre approbation. L’approbation d’un bot système ne compte pas. Une demande de modifications ultérieure de la même personne la retire.
2. Un résumé du comportement. Une section de la description de la pull request intitulée ## Behaviour (ou Behavior, Behaviour change, Behaviour summary), avec au moins une phrase sur ce qui change pour les utilisateurs ou les systèmes. C’est ce que voit un relecteur, ou toute personne qui lit l’historique plus tard, quand personne ne lit le diff ligne par ligne.

Si votre organisation utilise la revue IA avec sa propre clé de fournisseur, vous pouvez faire compter une revue IA terminée sur le commit comme résumé : activez Compter la revue IA comme résumé du comportement dans les paramètres (ai_review_summary). C’est désactivé par défaut. Les niveaux de risque n’envoient eux-mêmes jamais de code nulle part.

La dispense des propriétaires de l’organisation. Lorsqu’une règle de branche n’applique pas la protection aux propriétaires de l’organisation, la propre pull request d’un propriétaire n’a besoin d’aucune approbation, y compris les pull requests que son agent de code ouvre pour lui. Les niveaux de risque suivent la même règle et l’indiquent : le statut affiche « approval waived (org owner …) ». Sur une branche sans aucune règle de protection, Forgejo n’exige d’approbation de personne : la propre pull request d’un propriétaire y est donc aussi dispensée, et le statut affiche « approval waived (no branch rule) » ; celle d’un membre a toujours besoin d’une approbation. Le résumé du comportement est toujours exigé. Pour que les modifications à risque élevé des propriétaires soient approuvées par une deuxième personne, cochez Appliquer la protection aussi aux propriétaires/administrateurs de l’organisation sur la règle de branche.

Le statut n’attend jamais

fremforge/risk-tier n’est jamais pending. Il vaut success ou warning, et chaque résultat est définitif lorsqu’il est publié :

• Pas de fichier de politique : success, « No risk policy ».
• Une politique qui ne s’analyse pas : success, en indiquant que la politique est invalide. Rien n’est fusionné automatiquement.
• Tout ce que fremforge ne peut pas lire à temps (20 secondes) : success, en indiquant que le niveau n’est pas disponible et que la vérification laisse passer. Rien n’est fusionné automatiquement.

fremforge publie le statut quelques secondes après qu’une pull request a été ouverte, a reçu un push, a été modifiée, étiquetée ou relue. Une tâche lancée toutes les 5 minutes publie tout statut manquant et réexamine les pull requests à risque élevé qui sont toujours en attente.

Sur les groupes de la file de fusion, fremforge publie le niveau de l’ensemble de la modification du groupe en success, à titre d’information. Les approbations sont vérifiées sur chaque pull request.

fremforge n’ajoute pas fremforge/risk-tier à vos règles de branche. Aujourd’hui, il est affiché, pas exigé.

Fusion automatique pour le risque faible

Avec le mode on et auto_merge_low: true, fremforge arme la fusion automatique sur une pull request dont le risque est positivement faible. Forgejo la fusionne alors lorsque toutes les vérifications requises réussissent et que les approbations de la règle de branche sont réunies. Armer ne contourne jamais une vérification ni une approbation.

fremforge n’arme pas :

• ce qui n’est pas low, ni une pull request dont il n’a pas pu déterminer le niveau ;
• un brouillon, ni un titre commençant par WIP ;
• une pull request portant l’étiquette risk-tier/no-auto-merge ou do-not-merge ;
• une pull request qu’une personne a désarmée, jusqu’à ce qu’elle reçoive un nouveau push ;
• les pull requests Renovate, qui suivent vos paramètres de fusion automatique des mises à jour des dépendances.

Si un push relève le niveau d’une pull request que fremforge a armée, fremforge annule son armement. Il n’annule jamais un armement fait par une personne.

Dans la console

Les propriétaires de l’organisation trouvent les niveaux de risque sous Build et déploiement → Active work (https://frem.sh/<org>/_admin/active-work) :

• La carte Niveaux de risque définit le mode, la fusion automatique pour le risque faible et si la revue IA compte comme résumé. Le dépôt de politique de l’organisation se définit via l’API.
• Chaque pull request de la page affiche son niveau sous forme de badge. Ouvrez-le pour voir pourquoi : le fichier et la règle qui ont fixé le niveau, le nombre de fichiers modifiés et, pour le risque élevé, qui a approuvé ou quelle dispense s’applique, et d’où vient le résumé du comportement. La page montre ce que fremforge a publié en dernier pour la pull request : une pull request n’y apparaît donc qu’une fois son niveau publié.

Fantôme, activé et désactivé

Commencez en mode fantôme pendant une semaine et lisez les statuts et les événements would_arm avant d’activer la fusion automatique.

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

Le jeton doit avoir policy:write ; GET sur le même chemin nécessite policy:read. Chaque modification est auditée sous risk_tier.settings_updated.

Pourquoi une pull request a son niveau

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

La réponse donne le tier, le fichier et la règle qui l’ont fixé (decided_by), ce dont une pull request à risque élevé a encore besoin (needs), qui l’a approuvée ou quelle dispense (waiver) s’applique, d’où vient le résumé du comportement, et si elle serait fusionnée automatiquement. Cela fonctionne aussi lorsque le mode est off, ce qui vous permet de tester une politique sur de vraies pull requests avant de l’activer. Le jeton doit avoir findings:read, ou un accès en lecture au dépôt. Les agents de code obtiennent la même réponse avec l’outil MCP get_pull_request_risk_tier.