Branch-Schutz

Der Branch-Schutz in fremforge folgt dem Modell von Forgejo: Regeln werden per Glob-Muster an Branches gebunden, setzen Anforderungen an Reviews, Status und Historie durch und blockieren Schreibvorgänge, die dagegen verstoßen. fremforge ergänzt organisationsweite Standards, damit dieselbe Haltung für jedes Repository gilt, ohne dass die Konfiguration pro Repository auseinanderdriftet.

Organisationsstandards und Übersteuerungen pro Repository

Sicherheit › Richtlinien › Repository-Regeln legt die Regeln fest, die für jedes Repository der Organisation gelten. Ein neues Repository erhält bei seiner Erstellung eine Regel für jedes Muster in der Liste der geschützten Branches der Organisation (standardmäßig main, master, release/*), plus seinen Standard-Branch, falls kein Muster ihn abdeckt. Das gilt auch für ein leeres Repository, etwa eines, das mit POST /api/v1/orgs/{org}/repos angelegt wurde: Es ist sofort geschützt, und nur die Standarddateien fehlen, bis es einen ersten Commit hat. Das Speichern der Standards wendet sie sofort auf die bestehenden Repositorys der Organisation an, und ein stündlicher Abgleich führt denselben Durchlauf als Sicherheitsnetz aus. Bei einem Repository ohne Schutz legt er die Regeln der Organisation an und setzt, sofern die Organisation ihre Repository-Regeln gespeichert hat, den Standard-Merge-Stil und das Löschen des Branches nach dem Merge auf die Werte der Organisation. Bei einem Repository mit eigenen Regeln ergänzt er die Regeln für jedes Organisationsmuster, das dem Repository fehlt, und ändert ansonsten nur die wenigen Einstellungen, die unter Was der Organisationsstandard an bestehenden Regeln ändert aufgeführt sind. Er überschreibt nie eine Regel, die ein Repository-Admin gesetzt hat. Repositorys, die bereits geschützt sind, aber schwächer geworden sind als der Organisationsstandard, meldet die Drift-Erkennung als Benachrichtigung, statt sie automatisch zurückzusetzen (siehe unten).

Organisationen, die nie Repository-Regeln gespeichert haben

Eine Organisation, die Repository-Regeln nie gespeichert hat, erhält bei der Erstellung und im stündlichen Durchlauf die fremforge-Baseline, als hätte sie diese gespeichert: Ein Pull Request ist erforderlich, mit 1 Freigabe, veraltete Freigaben werden verworfen, die erforderlichen fremforge-Checks gelten, Force-Pushes sind gesperrt und Owner eingeschlossen, auf main, master, release/* und dem Standard-Branch des Repositorys. Bis zum 28. Oktober 2026 erhielten die Repositorys einer solchen Organisation bei der Erstellung eine main-Regel, die direkte Pushes erlaubte, und nichts aus dem stündlichen Durchlauf.

Um das zu ändern, öffne Sicherheit › Richtlinien › Repository-Regeln, stelle ein, was du willst, und speichere: Deine gespeicherten Regeln ersetzen die Baseline. Soll fremforge überhaupt keinen Schutz anwenden, entferne den Haken bei Branch-Schutz auf neue Repositorys anwenden und speichere. Die Organisation wird dann aus dem stündlichen Durchlauf herausgenommen, und ihre Repositorys behalten die Regeln, die sie bereits haben.

Leere Repositorys

Eine Regel, die einen Pull Request verlangt, weist auch den Push zurück, der den Branch anlegen würde, und ein leeres Repository hat keinen Branch, auf den ein Pull Request zielen könnte. Solange ein Repository leer ist, sind seine Regeln daher vollständig, akzeptieren aber noch einen direkten Push. Pushe deinen ersten Commit wie gewohnt auf den Standard-Branch. Sobald fremforge diesen Push empfängt, innerhalb von Sekunden, gelten die Regeln wie bei jedem anderen Repository nur noch für Pull Requests, sodass ein zweiter direkter Push abgewiesen wird.

Übersteuerungen pro Repository stehen auf der Einstellungsseite des Repositorys (/<org>/<repo>/settings/branches). Übersteuere nur, wenn das Repository eine echte Ausnahme von der Richtlinie hat; die meisten Teams setzen den Organisationsstandard einmal und fassen Regeln auf Repository-Ebene nie an.

Einstellungen, die direkt Forgejo entsprechen

Pull Request verlangen. Direkte Pushes auf den geschützten Branch werden abgewiesen (enable_push: false in Forgejo), sodass ein Pull Request der einzige Weg hinein ist. Erst das macht erforderliche Reviews und Checks verbindlich: Ein direkter Push umgeht den Pull Request, an dem sie hängen. In der fremforge-Baseline eingeschaltet. Die eigene Automatisierung von fremforge (Abhängigkeits-Updates, AutoFix, der .gitattributes-Backfill) öffnet ebenfalls Pull Requests und funktioniert daher auch auf einem Branch, der nur Pull Requests annimmt.
Pull-Request-Reviews vor dem Merge verlangen. Lege eine Mindestzahl an Reviewern fest (typischerweise 1 oder 2). Verwirf veraltete Reviews bei einem Push, damit Freigaben, die einfach durchgewunken wurden, ein nachträgliches Force-Amend nicht überleben.
Bestandene Status-Checks vor dem Merge verlangen. Nenne die Status-Kontexte, die Erfolg melden müssen. Der Organisationsstandard von fremforge verlangt sieben, und wer nur einige davon verlangt, nimmt den übrigen die Möglichkeit, einen Merge zu blockieren:
- fremforge/sast: statische Analyse
- fremforge/dep-scan: Schwachstellen in Abhängigkeiten
- fremforge/license-scan: Lizenzrichtlinie
- fremforge/image-scan: Schwachstellen und Secrets in den Container-Images und Dateien des Repositorys
- fremforge/cosign-verify: Signaturprüfung von per Digest festgelegten Images (nur informativ: besteht immer; siehe Image-Signaturen)
- fremforge/secret-scan: Erkennung von committeten Secrets
- fremforge/release-age: hält einen automatisierten Abhängigkeits-Update-Pull-Request zurück, bis jede Version, die seine Lockfile auflöst, mindestens so lange veröffentlicht ist wie das Release-Alter deiner Organisation (3 Tage, sofern ein Owner es nicht geändert hat; 24 Stunden für eine Korrektur, die eine geprüfte Advisory nennt, der Sicherheitskorrektur-Weg)
Ein achter Check, fremforge/iac-scan (Fehlkonfigurationen in Infrastructure as Code, siehe IaC-Scanning), meldet sich seit dem 17. Oktober 2026 bei jedem Pull Request und wird Organisation für Organisation zum erforderlichen Check, damit kein Pull Request, der vor seiner Einführung geöffnet wurde, auf ihn wartet. Bis er für deine Organisation erforderlich ist, meldet er, ohne selbst zu blockieren; du kannst ihn jederzeit selbst zu deinen erforderlichen Checks hinzufügen.
Der Organisationsstandard verlangt alle sieben; wenn du die erforderlichen Checks von Hand setzt, führe alle sieben auf, und fremforge/iac-scan, wenn er blockieren soll. fremforge/release-age blockiert nur automatisierte Abhängigkeits-Update-Pull-Requests, und nur bis ihre Versionen das Release-Alter erreichen; bei einem Pull Request, den eine Person geöffnet hat, meldet er frische Versionen, ohne den PR zurückzuhalten. Ein Scanner, den du für eine Organisation oder ein Repository auf off stellst, wird innerhalb einer Stunde aus den erforderlichen Checks entfernt, da ein Scanner auf off nichts meldet. Was jeder einzelne abdeckt, steht unter Scans erneut ausführen.
Signierte Commits verlangen. Ist das eingeschaltet, werden unsignierte Commits auf dem geschützten Branch beim Push abgewiesen. Den Weg zum Signieren von Commits mit kurzlebigen Sigstore-Zertifikaten beschreibt Cosign.
Lineare Historie verlangen. Ist das aktiviert, deaktiviert fremforge Merge-Commits im Repository: Merges erfolgen nur per Squash oder Rebase, sodass der geschützte Branch eine lineare Historie behält.
Force-Pushes sperren. Weist --force auf dem geschützten Branch vollständig ab.
Löschen des Branches sperren. Ein geschützter Branch kann nicht gelöscht werden. Das ergibt sich daraus, dass eine Branch-Schutzregel an ihm hängt, und ist kein eigener Schalter. Solange der Branch geschützt ist, werden Löschvorgänge auf ihm abgewiesen.

Was fremforge zusätzlich bietet

Schutz auch für Organisations-Owner/Admins durchsetzen. Ein Schalter pro Mandant auf der Admin-Seite Repos, „Schutz auch für Organisations-Owner/Admins durchsetzen“ (apply_to_admins in Forgejo), der standardmäßig eingeschaltet ist. Eingeschaltet braucht ein Pull Request, den ein Owner der Organisation geöffnet hat, die erforderlichen Freigaben wie jeder andere; ausgeschaltet entfällt die Zahl der Freigaben für Pull Requests, die ein Owner der Organisation öffnet. Der Schalter regelt nur Freigaben. Erforderliche Status-Checks gelten für jeden Pull Request, und ein Owner der Organisation kann als Repository-Admin trotzdem bewusst an ihnen vorbei mergen, mit dem force merge von Forgejo („merge anyway“ im Merge-Feld oder force_merge in der Merge-API). Das ist der Notausgang für einen hängenden oder fehlerhaften Check; er mergt eine Änderung, die die Checks nicht freigegeben haben, also setze ihn sparsam ein. Soll ein fremforge-Check gar nicht mehr blockieren, stelle seinen Scanner stattdessen für die Organisation oder das Repository auf audit oder off. Damit Abhängigkeitsbefunde, die nicht erreichbar sind, fremforge/dep-scan nicht blockieren, gibt es eine optionale Richtlinie: siehe Erreichbarkeit: bei nicht erreichbaren Befunden nicht blockieren, und lies zuerst, welches Risiko sie hat.
Review durch Code-Owner verlangen. Setzt in den Regeln des geschützten Branches die Forgejo-Einstellung Block merge on official review requests. Wird ein Pull Request geöffnet, sorgt eine CODEOWNERS-Datei (im Wurzelverzeichnis des Repositorys, in docs/, .forgejo/ oder .gitea/) dafür, dass Forgejo ein Review von den Ownern der geänderten Pfade anfordert; mit dieser Einstellung kann der Pull Request nicht gemergt werden, solange eine dieser Anfragen offen ist, sodass die Code-Owner ihn reviewen müssen. Zwei Dinge solltest du wissen: Er blockiert bei jeder offenen Review-Anfrage an einen offiziellen Reviewer, auch bei einer, die du von Hand hinzufügst; und ein Code-Owner, der auf dem Branch nicht freigeben darf (zum Beispiel jemand, der kein Owner ist, wenn Freigaben auf das Team Owners beschränkt sind), ist kein offizieller Reviewer, sodass seine Anfrage nicht blockiert. Ohne CODEOWNERS-Datei wird niemand automatisch angefragt, und die Einstellung ändert nichts.
Allowlist für die Status-Checks, die fremforge meldet. Die sieben maßgeblichen Namen stehen oben. Sie werden intern an einer einzigen Stelle gehalten, die von der Einrichtung bei der Erstellung und vom stündlichen Backfill gemeinsam genutzt wird, sodass der Satz, den ein neues Repository erhält, und der Satz, den der Backfill durchsetzt, nicht auseinanderlaufen können.
Drift-Erkennung. Ein separater täglicher Lückenscan markiert jedes Repository, dessen Branch-Schutz fehlt oder schwächer ist als der Organisationsstandard; schwächer heißt: weniger erforderliche Freigaben oder ein Check, den der Standard verlangt und das Repository nicht. (Der oben beschriebene Backfill läuft stündlich und füllt nur Repositorys ohne Schutz auf; dieser tägliche Scan bemerkt ein Repository, das zwar geschützt ist, aber gelockert wurde.) Das erscheint als eigene Admin-Benachrichtigung in der Glocke, „N Repositorys mit abgeschwächtem Branch-Schutz“, die auf die Admin-Seite Repos verlinkt. Abgesehen von den im nächsten Abschnitt aufgeführten Einstellungen erkennt und meldet sie nur: fremforge setzt abgeschwächte Einstellungen nicht automatisch zurück, weil die ausdrücklichen Einstellungen eines Repository-Owners Vorrang haben. Nutze die Benachrichtigung, um zu entscheiden, ob du beim Repository-Owner nachhakst.

Was der Organisationsstandard an bestehenden Regeln ändert

Bei einem Repository, das bereits eigenen Schutz hat, lässt fremforge die Regeln in Ruhe, mit Ausnahme der folgenden Punkte, die jeweils einzeln geändert werden, ohne eine andere Einstellung der Regel anzufassen:

Die erforderlichen fremforge-Checks werden hinzugefügt und für einen Scanner auf off entfernt.
Schutz auch für Organisations-Owner/Admins durchsetzen folgt der Einstellung der Organisation, in beide Richtungen.
Pull Request verlangen macht, wenn es in der Organisation eingeschaltet ist, auch bestehende Regeln zu Regeln, die nur Pull Requests annehmen. Eine Regel, die festlegt, wer pushen darf (eine Push-Allowlist aus Benutzern, Teams oder Deploy Keys), bleibt unverändert: Das ist eine bewusste Entscheidung, jemanden pushen zu lassen, und die Drift-Erkennung meldet sie weiterhin.
Review durch Code-Owner verlangen wird, wenn es in der Organisation eingeschaltet ist, für bestehende Regeln eingeschaltet.
Fehlende Muster. Für ein Organisationsmuster (oder den Standard-Branch), für das das Repository keine Regel hat, wird eine angelegt. Das Anlegen ändert nie eine bestehende Regel.

Die letzten beiden verschärfen nur. Schaltest du einen der beiden auf Organisationsebene aus, wird er auf neue Regeln nicht mehr angewendet; Regeln, die ihn bereits haben, behalten ihn, bis ein Repository-Admin sie in den Branch-Einstellungen des Repositorys ändert.

Nur Regeln auf den geschützten Branch-Mustern der Organisation (und dem Standard-Branch) werden angefasst. Jede Änderung wird pro Repository im Audit-Ereignis repo-defaults.branch-protection.retro-applied aufgeführt. Bis zum 28. Oktober 2026 hat fremforge nie eine Regel für ein Muster angelegt, das ein Repository-Admin ungeschützt gelassen hatte; jetzt tut es das. Soll ein Branch ungeschützt bleiben, nimm sein Muster aus der Liste der geschützten Branches der Organisation heraus.

Entfernt: Standard-Repository-Vorlage

Die Seite Repos hatte früher ein Feld Default repository template. Es wurde am 2026-10-14 entfernt, weil es zwar gespeichert, aber nie angewendet wurde: Repositorys werden in Forgejo angelegt, und Forgejo kann aus einer Vorlage nur ein neues Repository erzeugen, aber keines befüllen, das ein Mitglied bereits angelegt hat. Um Repositorys aus einer Vorlage zu starten, markiere das Quell-Repository in seinen Einstellungen als Vorlage und wähle es im Forgejo-Formular New Repository aus, oder rufe POST /api/v1/repos/{template_owner}/{template_repo}/generate auf. Die API weist einen Wert für default_template_repo jetzt mit removed-setting ab.

Einrichten

Öffne Sicherheit › Richtlinien › Repository-Regeln.
Wähle das Branch-Glob-Muster (typischerweise main oder main, master, release/*).
Setze die oben beschriebenen Schalter. Speichere.
Die Änderung wird im Audit-Log als repo-defaults.branch-protection.updated erfasst. Eine rückwirkende Anwendung auf bestehende Repositorys ohne Schutz wird als repo-defaults.branch-protection.retro-applied protokolliert, und das Zurücksetzen der Organisationsstandards auf die fremforge-Baseline als repo-defaults.reset-baseline.

Siehe auch

Scorecard: Der Branch-Schutz bestimmt den OpenSSF-Score Branch-Protection.
Authentifizierungsrichtlinie: die übergreifende Haltung (signierte Commits, SSH-Transport, MFA).
Cosign: die Umsetzung erforderlicher signierter Commits.

Befund-Warnungen Compliance-Bericht