f0090 - Branch-Schutz für `main` — PR-Pflicht + CI als Gate
Quelle: pkr-lab/pkr-lab-docs/capulus/capulus-core/f-cicd-automatisierung/f0090-branch-schutz-main.md
Branch-Schutz für main — PR-Pflicht + CI als Gate
main ist die Quelle von TECH und PROD: ein Commit dort wird von ArgoCD sofort
ausgerollt. Bis September 2026 gingen Änderungen direkt per Push auf main, die
CI lief erst danach und konnte einen Fehler nur noch melden
(so blieb z. B. ein kaputter Renovate-Bump an pacmans go.mod bis zum
Image-Build unbemerkt). Das Ruleset „main: PR + CI“ macht daraus ein echtes
Gate: Änderungen kommen nur noch per Pull Request, und der PR lässt sich erst
mergen, wenn die CI-Jobs grün sind.
Was das Ruleset erzwingt
| Regel | Wirkung |
|---|---|
| Pull Request | Kein Direkt-Push auf main. Kein Pflicht-Review (0 Freigaben), du arbeitest allein — die Sicherheit kommt aus den Checks. |
| Pflicht-Checks | make lint (yamllint, helm lint), helm template \| kubeconform, go build, vet, test, tidy, token register, gitleaks — fünf der sechs Jobs aus ci.yml |
| Kein Force-Push, kein Löschen | main ist nicht überschreibbar |
| „Up to date“ nicht verlangt | strict_required_status_checks_policy: false — sonst müsste jeder PR nach jedem anderen Merge neu gebaut werden |
Notausgang: Repo-Admins dürfen einen PR trotz roter oder fehlender Checks
mergen (bypass_mode: pull_request), aber weiterhin nicht direkt pushen.
Das verhindert einen Deadlock, wenn die CI selbst kaputt ist (der Fix für die CI
müsste sonst durch die kaputte CI).
Die Image-Builds aus build-images.yml sind bewusst
keine Pflicht-Checks: der Pfadfilter lässt den Workflow bei PRs ohne
Image-Änderung gar nicht laufen, ein Pflicht-Check bliebe dann ewig auf „pending“.
Dasselbe gilt für CodeQL: der Workflow
überspringt reine Doku-PRs, und der Swift-Job auf macOS soll einen Merge nicht
blockieren, wenn er selbst ein Problem hat. Neue Funde ab high sieht man trotzdem
als roten Check „Code scanning results“ im PR.
Aktivieren
Das Ruleset wird per Skript angelegt (reproduzierbar, im Repo versioniert):
scripts/setup-main-ruleset.sh --dry-run # zeigt das JSON
scripts/setup-main-ruleset.sh # anlegen bzw. aktualisieren (gh als Admin)
Reihenfolge ist wichtig: erst die neue ci.yml (mit allen fünf Jobs) auf
main bringen, dann das Skript ausführen. Andernfalls verlangt das Ruleset
Checks, die es nirgends gibt, und der erste PR bleibt auf „pending“. Nach dem
Aktivieren ist auch der eigene Push auf main gesperrt.
Arbeitsablauf danach
- Branch anlegen, committen, pushen (
git push -u origin <branch>). - PR gegen
mainöffnen (gh pr createoder im Browser) — die CI startet. - Grün → mergen. Rot → fixen und nachpushen (der Lauf wird ersetzt).
Wer sonst noch PRs aufmacht:
| Quelle | Bemerkung |
|---|---|
| Renovate (App und Fallback-Workflow) | PRs sind jetzt gegated. Ein kaputter Bump (Major-Sprung mit geändertem Import-Pfad, halb aktualisierte go.mod) bleibt rot statt auf main zu landen. |
| ENTW-Promotion | öffnet PRs mit einem PAT (sonst liefe die CI auf dem PR nicht an) und mergt nie selbst |
| Dependabot | nur Sicherheits-PRs (fix(deps): …, Labels dependencies und security). Die CI läuft darauf ohne PAT, Dependabot-PRs lösen Workflows aus. Gemergt wird von Hand. |
| Kleine GitOps-Schritte (Migration: App stoppen, kopieren, starten) | ebenfalls per PR. Ein Lauf dauert ca. 2 Minuten (der make lint-Job ist der längste). Nur im Notfall per Admin-Bypass mergen. |
Nicht betroffen ist mirror-gitlab.yml (liest main). release.yml pusht seit der Umstellung auf die zentralen Workflows den Commit
chore(release): X [skip ci] mit CHANGELOG.md direkt auf main und braucht bei aktivem Ruleset eine Ausnahme (siehe oben).
Vorhandene Rulesets im Repo
Stand 2026-10-19: Alle Rulesets sind deaktiviert (enforcement: disabled, geändert am 2026-10-18 gegen 15:29 Uhr während der Umstellung auf die
zentralen Release-Workflows). Es gibt auch keinen klassischen Branch-Schutz. Ein Merge nach main ist damit nicht durch Checks gesperrt, und der
Release-Commit chore(release): X [skip ci] kann direkt auf main landen.
| Ruleset | Stand | Bemerkung |
|---|---|---|
entw-1 |
deaktiviert | entw: kein Löschen, kein Force-Push |
Protect MAIN |
deaktiviert | Löschen/Force-Push/PR (0 Freigaben) plus code_quality, trifft main und entw |
main: PR + CI |
deaktiviert | PR-Pflicht, Admin-Bypass (pull_request) und Pflicht-Checks. Die gespeicherten Check-Namen sind veraltet (siehe unten) |
Das Ruleset entw-2 aus früheren Ständen existiert nicht mehr.
Wiedereinschalten: Das gespeicherte Ruleset main: PR + CI verlangt make lint (yamllint, ansible-lint, helm lint) und docs links. Beide Jobs
gibt es nicht mehr (der Job heißt make lint (yamllint, helm lint), die Link-Prüfung läuft in pkr-lab-docs), isc-news-bot (typecheck, unit und Mock-Tests) fehlt. Ein aktiviertes Ruleset würde jeden PR auf „pending“ halten. Zuerst scripts/setup-main-ruleset.sh ausführen, das die aktuelle Liste
enthält. Es legt das Ruleset als active an.
Ausnahme für den Release-Commit: Das Ruleset verlangt Pull Requests, der Release-Workflow pusht aber CHANGELOG.md direkt auf main. Der
GITHUB_TOKEN (github-actions[bot]) lässt sich nicht als Bypass-Akteur eintragen (nach Community-Berichten; eine offizielle Quelle dazu wurde nicht
gefunden, vor dem Einschalten ausprobieren). Möglichkeiten: ein GitHub-App-Token oder ein Deploy-Key bzw. PAT eines Akteurs mit Bypass für den Schritt
semantic-release (Änderung im zentralen Workflow pkr-lab/.github), oder Rulesets ausgeschaltet lassen. Entscheidung offen, siehe
600b0.
Stolperfallen
- Pfadgefilterte Workflows als Pflicht-Check bleiben auf „pending“, wenn der
Filter nicht greift. Nur Jobs ohne Pfadfilter (die vier ausci.yml) sind Pflicht. GITHUB_TOKEN-PRs lösen keine CI aus. Automatisch erzeugte PRs brauchen ein
PAT (siehe Promotion), sonst sind sie nicht mergbar.- Check-Namen im Ruleset müssen den
name:der Jobs inci.ymlentsprechen.
Wird ein Job umbenannt oder kommt einer dazu (zuletzttoken register), in
scripts/setup-main-ruleset.shnachziehen und das Skript erneut ausführen: es
aktualisiert das vorhandene Ruleset. - Lock-out: Ist das Ruleset aktiv und die CI kaputt, hilft nur der
Admin-Bypass am PR (oder das Ruleset unter Settings → Rules aufdisabled
setzen).
Fehlersuche
scripts/setup-main-ruleset.sh --dry-run # Soll-Ruleset als JSON
gh api repos/pkr-lab/capulus-core/rulesets --jq '.[] | {id,name,enforcement}'
| Symptom | Ursache | Lösung |
|---|---|---|
Push auf main abgelehnt (Changes must be made through a pull request) |
Ruleset aktiv | Änderung per PR |
PR lässt sich nicht mergen, Check steht auf pending |
Pflicht-Check läuft nicht (Pfadfilter) oder der Name im Ruleset passt nicht zum Job | Namen in setup-main-ruleset.sh und ci.yml abgleichen, Skript erneut ausführen |
| PR lässt sich nicht mergen, Check rot | CI-Fehler | f0070, lokal nachstellen |
| Merge trotz roter CI nötig (CI selbst defekt) | Notausgang | Repo-Admin darf den PR trotz roter Checks mergen (bypass_mode: pull_request) |
Skript meldet Resource not accessible |
gh ohne Admin-Recht |
mit Admin-Konto anmelden |
| Renovate- oder Promotions-PRs blockiert | ihre Checks laufen nicht (PR mit GITHUB_TOKEN) |
PAT verwenden (f00c0) |
strict-Fehler („Branch muss aktuell sein“) |
nicht erzwungen | Einstellung strict_required_status_checks_policy: false prüfen |
Allgemeine Fehlersuche: zentrale Fehlersuche.