Protection de branche

La protection de branche sur fremforge suit le modèle de Forgejo : les règles s’attachent aux branches par motif glob, imposent des exigences de relecture, de statut et d’historique, et bloquent les écritures qui les enfreignent. fremforge ajoute des valeurs par défaut à l’échelle de l’organisation, afin que la même posture s’applique à chaque dépôt sans dérive de configuration d’un dépôt à l’autre.

Valeurs par défaut de l’organisation et surcharges par dépôt

Sécurité › Politiques › Règles des dépôts définit les règles qui s’appliquent à chaque dépôt de l’organisation. À sa création, un nouveau dépôt reçoit une règle pour chaque motif de la liste des branches protégées de l’organisation (main, master, release/* par défaut), plus sa branche par défaut si aucun motif ne la couvre. Cela vaut aussi pour un dépôt vide, par exemple créé avec POST /api/v1/orgs/{org}/repos : il est protégé immédiatement, et seuls les fichiers par défaut sont différés jusqu’à son premier commit. L’enregistrement des valeurs par défaut les applique immédiatement aux dépôts existants de l’organisation, et un réconciliateur horaire exécute la même passe comme filet de sécurité. Sur un dépôt sans protection, il crée les règles de l’organisation et, si l’organisation a enregistré ses règles des dépôts, aligne le style de fusion par défaut du dépôt et la suppression de branche après fusion sur les valeurs de l’organisation. Sur un dépôt qui a ses propres règles, il ajoute les règles pour tout motif de l’organisation qui manque au dépôt et, pour le reste, ne modifie que les quelques paramètres listés sous Ce que la valeur par défaut de l’organisation modifie sur les règles existantes. Il n’écrase jamais une règle définie par un administrateur du dépôt. Les dépôts qui ont déjà une protection mais qui ont dérivé vers un niveau plus faible que la valeur par défaut de l’organisation sont signalés par le détecteur de dérive sous forme d’alerte, et non rétablis automatiquement (voir ci-dessous).

Organisations qui n’ont jamais enregistré de règles des dépôts

Une organisation qui n’a jamais enregistré de Règles des dépôts reçoit la référence fremforge, à la création et lors de la passe horaire, comme si elle l’avait enregistrée : une pull request est requise, avec 1 approbation, les approbations obsolètes sont rejetées, les vérifications requises de fremforge s’appliquent, les force-push sont bloqués et les propriétaires sont inclus, sur main, master, release/* et la branche par défaut du dépôt. Jusqu’au 28 octobre 2026, les dépôts d’une telle organisation recevaient à la création une règle main acceptant les push directs, et rien lors de la passe horaire.

Pour la modifier, ouvrez Sécurité › Politiques › Règles des dépôts, définissez ce que vous voulez et enregistrez : vos règles enregistrées remplacent la référence. Pour que fremforge n’applique aucune protection, décochez Appliquer la protection de branche aux nouveaux dépôts et enregistrez. L’organisation est alors exclue de la passe horaire, et ses dépôts conservent les règles qu’ils ont déjà.

Dépôts vides

Une règle qui exige une pull request refuse aussi le push qui créerait la branche, et un dépôt vide n’a aucune branche qu’une pull request pourrait cibler. Tant qu’un dépôt est vide, ses règles sont donc complètes mais acceptent encore un push direct. Poussez votre premier commit sur la branche par défaut comme d’habitude. Dès que fremforge reçoit ce push, en quelques secondes, les règles deviennent « pull request uniquement » comme pour tout autre dépôt, et un second push direct est refusé.

Les surcharges par dépôt se trouvent sur la page des paramètres du dépôt (/<org>/<repo>/settings/branches). Ne surchargez que lorsque le dépôt fait l’objet d’une véritable exception de politique : la plupart des équipes définissent la valeur par défaut de l’organisation une fois et ne touchent jamais aux règles au niveau du dépôt.

Paramètres qui correspondent directement à Forgejo

• Exiger une pull request. Les push directs sur la branche protégée sont refusés (enable_push: false de Forgejo), si bien qu’une pull request est le seul point d’entrée. C’est ce qui rend contraignantes les relectures et vérifications requises : un push direct contourne la pull request à laquelle elles sont attachées. Activé dans la référence fremforge. L’automatisation propre à fremforge (mises à jour de dépendances, AutoFix, rattrapage de .gitattributes) ouvre elle aussi des pull requests, et continue donc de fonctionner sur une branche réservée aux PR.

• Exiger des relectures de pull request avant la fusion. Définissez un nombre minimal de relecteurs (généralement 1 ou 2). Rejetez les relectures obsolètes au push pour éviter qu’une approbation de complaisance survive à un amend forcé.

• Exiger la réussite des vérifications de statut avant la fusion. Nommez les contextes de statut qui doivent signaler un succès. La valeur par défaut de fremforge pour l’organisation en exige sept, et n’en exiger qu’une partie empêche les autres de bloquer une fusion :

  • fremforge/sast : analyse statique
  • fremforge/dep-scan : vulnérabilités des dépendances
  • fremforge/license-scan : politique de licences
  • fremforge/image-scan : vulnérabilités et secrets dans les images de conteneur et les fichiers du dépôt
  • fremforge/cosign-verify : vérification des signatures des images épinglées par condensé (informatif : il réussit toujours ; voir Signatures d’images)
  • fremforge/secret-scan : détection de secrets commités
  • fremforge/release-age : retient une pull request automatisée de mise à jour de dépendances jusqu’à ce que chaque version résolue par son fichier de verrouillage soit publiée depuis au moins l’âge de release de votre organisation (3 jours, sauf si un propriétaire l’a modifié ; 24 heures pour un correctif cité par un avis de sécurité vérifié, la voie des correctifs de sécurité)

  Une huitième, fremforge/iac-scan (erreurs de configuration de l’infrastructure as code, voir Analyse IaC), est publiée sur chaque pull request depuis le 17 octobre 2026 et devient une vérification requise organisation par organisation, afin qu’aucune pull request ouverte avant son existence ne l’attende. Tant qu’elle n’est pas requise pour votre organisation, elle rapporte sans bloquer d’elle-même ; vous pouvez l’ajouter vous-même à vos vérifications requises à tout moment.

  La valeur par défaut de l’organisation exige les sept ; si vous définissez les vérifications requises à la main, listez-les toutes les sept, plus fremforge/iac-scan si vous voulez qu’elle bloque. fremforge/release-age ne bloque que les pull requests automatisées de mise à jour de dépendances, et seulement jusqu’à ce que leurs versions atteignent l’âge de release ; sur une pull request ouverte par une personne, elle signale les versions récentes sans retenir la PR. Un scanner que vous passez à off pour une organisation ou un dépôt est retiré de ses vérifications requises dans l’heure, puisqu’un scanner off ne publie rien. Voir Relancer les analyses pour ce que couvre chacune.

• Exiger des commits signés. Lorsque cette option est activée, les commits non signés sur la branche protégée sont rejetés au push. Voir Cosign pour la signature de commits avec des certificats Sigstore de courte durée.

• Exiger un historique linéaire. Lorsque cette option est activée, fremforge désactive les commits de fusion sur le dépôt : les fusions se font uniquement par squash ou rebase, et la branche protégée garde un historique linéaire.

• Bloquer les force-push. Refuse entièrement --force sur la branche protégée.

• Bloquer la suppression de branche. Une branche protégée ne peut pas être supprimée : c’est inhérent à la présence d’une règle de protection de branche, et non un interrupteur séparé. Tant que la branche est protégée, les opérations de suppression la visant sont refusées.

Paramètres ajoutés par fremforge

• Appliquer la protection aussi aux propriétaires/administrateurs de l’organisation. Un interrupteur par tenant sur la page d’administration des dépôts, « Appliquer la protection aussi aux propriétaires/administrateurs de l’organisation » (apply_to_admins de Forgejo), activé par défaut. Activé, une pull request ouverte par un propriétaire de l’organisation a besoin des approbations requises comme celle de n’importe qui ; désactivé, le nombre d’approbations est levé pour les pull requests qu’ouvre un propriétaire de l’organisation. L’interrupteur ne régit que les approbations. Les vérifications de statut requises s’appliquent à chaque pull request, et un propriétaire de l’organisation, en tant qu’administrateur du dépôt, peut toujours délibérément fusionner malgré elles avec la force merge de Forgejo (« merge anyway » dans la zone de fusion, ou force_merge sur l’API de fusion). C’est l’échappatoire pour une vérification bloquée ou erronée ; elle fusionne une modification que les vérifications n’ont pas validée, utilisez-la donc avec parcimonie. Pour qu’une vérification fremforge ne bloque plus du tout, passez plutôt son scanner à audit ou off pour l’organisation ou le dépôt. Pour que les résultats de dépendances qui ne sont pas atteignables ne bloquent pas fremforge/dep-scan, il existe une politique optionnelle : voir Atteignabilité : ne pas bloquer sur les résultats non atteignables, et lisez d’abord ses risques.
• Exiger la relecture des propriétaires du code. Active Block merge on official review requests de Forgejo sur les règles de la branche protégée. Lorsqu’une pull request est ouverte, un fichier CODEOWNERS (à la racine du dépôt, dans docs/, .forgejo/ ou .gitea/) fait demander par Forgejo une relecture aux propriétaires des chemins modifiés ; avec ce paramètre activé, la pull request ne peut pas être fusionnée tant que l’une de ces demandes reste ouverte, si bien que les propriétaires du code doivent la relire. Deux points à connaître : il bloque sur toute demande de relecture ouverte adressée à un relecteur officiel, y compris une que vous ajoutez à la main ; et un propriétaire du code qui n’a pas le droit d’approuver sur la branche (par exemple un non-propriétaire lorsque les approbations sont réservées à l’équipe Owners) n’est pas un relecteur officiel, sa demande ne bloque donc pas. Sans fichier CODEOWNERS, personne n’est sollicité automatiquement et le paramètre ne change rien.
• Liste autorisée des vérifications de statut émises par fremforge. Les sept noms canoniques sont listés ci-dessus. Ils sont conservés en un seul endroit en interne, partagé entre l’installation à la création et le rattrapage horaire, de sorte que l’ensemble que reçoit un nouveau dépôt et celui qu’impose le rattrapage ne peuvent pas diverger.
• Détecteur de dérive. Une analyse d’écarts quotidienne distincte signale tout dépôt dont la protection de branche est absente ou plus faible que la valeur par défaut de l’organisation, plus faible signifiant moins d’approbations requises, ou une vérification exigée par la valeur par défaut que le dépôt n’exige pas. (Le rattrapage ci-dessus est horaire et ne complète que les dépôts sans protection ; c’est cette analyse quotidienne qui repère un dépôt protégé mais dont la protection a été assouplie.) Elle se présente comme une alerte distincte dans la cloche d’administration, « N dépôts avec une protection de branche affaiblie », avec un lien vers la page d’administration des dépôts. À part les paramètres listés dans la section suivante, elle se limite à détecter et alerter : fremforge ne rétablit pas automatiquement les paramètres affaiblis, car les choix explicites d’un propriétaire de dépôt priment. Servez-vous de l’alerte pour décider s’il faut en parler avec le propriétaire du dépôt.

Ce que la valeur par défaut de l’organisation modifie sur les règles existantes

Sur un dépôt qui a déjà sa propre protection, fremforge laisse les règles en l’état, à l’exception des éléments suivants, chacun modifié isolément sans toucher aux autres paramètres de la règle :

• Les vérifications requises de fremforge sont ajoutées, et retirées pour un scanner passé à off.
• Appliquer la protection aussi aux propriétaires/administrateurs de l’organisation suit le paramètre de l’organisation, dans les deux sens.
• Exiger une pull request, lorsque l’organisation l’a activé, rend aussi les règles existantes « PR uniquement ». Une règle qui nomme qui peut pousser (une liste autorisée de push composée d’utilisateurs, d’équipes ou de clés de déploiement) est laissée telle quelle : c’est un choix délibéré de laisser quelqu’un pousser, et le détecteur de dérive continue de le signaler.
• Exiger la relecture des propriétaires du code, lorsque l’organisation l’a activé, est activé sur les règles existantes.
• Motifs manquants. Une règle est créée pour un motif de l’organisation (ou la branche par défaut) pour lequel le dépôt n’a aucune règle. Sa création ne modifie jamais une règle existante.

Les deux derniers ne font que renforcer. Les désactiver au niveau de l’organisation cesse de les appliquer aux nouvelles règles ; les règles qui les ont déjà les conservent jusqu’à ce qu’un administrateur du dépôt les modifie dans les paramètres de branches du dépôt.

Seules les règles portant sur les motifs de branches protégées de l’organisation (et la branche par défaut) sont touchées. Chaque modification est listée, par dépôt, dans l’événement d’audit repo-defaults.branch-protection.retro-applied. Jusqu’au 28 octobre 2026, fremforge n’ajoutait jamais de règle pour un motif qu’un administrateur de dépôt avait laissé sans protection ; c’est désormais le cas, donc pour garder une branche sans protection, retirez son motif de la liste des branches protégées de l’organisation.

Supprimé : modèle de dépôt par défaut

La page Dépôts comportait autrefois un champ Default repository template. Il a été supprimé le 2026-10-14 car il était enregistré mais jamais appliqué : les dépôts sont créés dans Forgejo, et Forgejo ne peut générer qu’un nouveau dépôt à partir d’un modèle, pas en alimenter un qu’un membre a déjà créé. Pour démarrer des dépôts à partir d’un modèle, marquez le dépôt source comme modèle dans ses paramètres et choisissez-le dans le formulaire New Repository de Forgejo, ou appelez POST /api/v1/repos/{template_owner}/{template_repo}/generate. L’API refuse désormais une valeur pour default_template_repo avec removed-setting.

Mise en place

1. Ouvrez Sécurité › Politiques › Règles des dépôts.
2. Choisissez le glob de branches (généralement main ou main, master, release/*).
3. Réglez les interrupteurs ci-dessus. Enregistrez.
4. La modification est enregistrée dans le journal d’audit sous repo-defaults.branch-protection.updated. Une application rétroactive aux dépôts existants sans protection est journalisée sous repo-defaults.branch-protection.retro-applied, et la réinitialisation des valeurs par défaut de l’organisation à la référence fremforge sous repo-defaults.reset-baseline.

Voir aussi

• Scorecard : la protection de branche détermine le score OpenSSF Branch-Protection.
• Politique d’authentification : la posture plus large (commits signés, transport SSH, MFA).
• Cosign : mise en œuvre des commits signés obligatoires.