PKR-Lab

f0080 - ENTW → main — automatischer PR nach grüner CI

Quelle: pkr-lab/pkr-lab-docs/capulus/capulus-core/f-cicd-automatisierung/f0080-entw-promotion.md

ENTW → main — automatischer PR nach grüner CI

.github/workflows/promote-entw.yml
übergibt Änderungen, die auf dem Branch entw gelandet sind, als Pull
Request an main
— aber erst, wenn die CI auf entw grün ist. entw ist
die Git-Quelle des ENTW-Clusters (argocd_repo_revision: entw in
capulus-ansible/host_vars/entw-vm/vars.yml); main ist die Quelle von TECH und PROD.
Was auf ENTW getestet wurde, kommt so ohne Handarbeit als fertiger PR nach
main, wo das Ruleset die Pflicht-Checks prüft und
du den Merge bestätigst.

Das ist die erste, bewusst schlanke Stufe der Promotion-Pipeline aus
40080, Baustein 6
(Phase 4). Sie überträgt alles außer den ENTW-Apps (Doku, Skripte, Playbooks). Die Apps unter
argocd/apps/entw/ (existiert seit 2026-09-20 auf dem Branch entw, siehe
b0050) gehen ihren eigenen Weg: die
Promotion-Kette überträgt deren Versionen nach ENTW-Gesundheit (24 h)
über TECH nach PROD. Hier reicht die CI als Freigabe.


Ablauf

flowchart TD
    Push["Commit auf entw<br/>(per PR)"] --> Cron["entw-trigger.yml startet sofort,<br/>Cron stündlich als Fallback<br/>promote-entw.yml auf main"]
    Cron --> Detect{"neue entw-Commits<br/>seit Tag entw-promoted?"}
    Detect -->|nein| Ende["nichts zu tun"]
    Detect -->|ja| CI["ci.yml gegen ref=entw<br/>lint, kubeconform, go, gitleaks"]
    CI -->|rot| Issue["Issue 'ENTW-CI rot',<br/>Tag bleibt, kein PR"]
    CI -->|grün| Pick["Cherry-Pick der Commits<br/>auf promote/entw-SHA (ab main)"]
    Pick -->|Konflikt| Issue2["Issue 'Konflikt',<br/>Tag bleibt, kein PR"]
    Pick -->|ok| PR["PR nach main<br/>(Draft bei Alt-Layout-Dateien)"]
    PR --> Tag["Tag entw-promoted<br/>auf entw-Stand umlegen"]
    Tag --> Merge["du: PR prüfen + mergen<br/>= Rollout auf TECH und PROD"]
Job Was
detect Vergleicht origin/entw mit dem Tag entw-promoted; gibt es neue Commits, die main noch nicht hat? Überspringt Stände, für die schon ein offenes Issue existiert.
ci Ruft ci.yml als wiederverwendbaren Workflow mit ref: entw auf — exakt dieselben vier Jobs wie auf einem PR.
ci-failed Bei rotem CI: Issue mit Link zum Lauf. Der Cron prüft diesen Stand danach nicht mehr alle 15 Minuten neu.
promote Cherry-Pick, PR, Tag umlegen (Logik in scripts/promote-entw.sh).

Der Tag entw-promoted

Der Tag ist die Marke „bis hierhin wurde entw an main übergeben“ und
wird nur nach erfolgreich geöffnetem PR (oder nach „nichts zu übergeben“)
auf den neuen entw-Stand gesetzt. Die Commits eines PR sind genau die
zwischen altem Tag und neuer entw-Spitze, abzüglich allem, was main schon
enthält. Ohne Tag (erster Lauf) gilt der Merge-Base von main und entw.
Der Tag bleibt auch stehen, wenn der PR noch offen ist — dieselben Commits
kommen nicht ein zweites Mal.

Welche Commits übernommen werden

Fehlerfälle

Fall Verhalten Was du tust
CI auf entw rot Issue ENTW-CI rot bei <sha>, kein PR, Tag bleibt Fehler auf entw beheben. Der neue Stand wird automatisch neu geprüft.
Cherry-Pick-Konflikt Issue ENTW -> main: Konflikt bei <sha> mit Konfliktdateien, Lauf rot, Tag bleibt Änderung von Hand per PR nach main bringen, danach Tag setzen (Befehl steht im Issue) — oder auf entw den Commit mit [entw-only] versehen.
Nichts Übertragbares (alles [entw-only] oder schon in main) Kein PR, Tag wird trotzdem umgelegt —
PAT fehlt promote bricht mit Hinweis ab Secret anlegen (siehe unten).

Jede erfolgreiche Promotion schließt alle offenen entw-promotion-Issues.

Voraussetzung: Personal Access Token

promote braucht ein PAT, weil PRs und Pushes mit dem Standard-GITHUB_TOKEN
keine weiteren Workflows auslösen
— die CI auf dem PR bliebe aus, und der
Pflicht-Check würde ewig auf „pending“ stehen. Der Workflow nimmt das Repo-Secret
PROMOTE_TOKEN, ersatzweise RENOVATE_TOKEN (fine-grained PAT nur für dieses
Repo, Contents, Pull requests, Issues, Workflows = Read and write —
das ist die Rechteliste, die renovate.yml
ohnehin nutzt). Ein eigenes Secret ist sauberer, weil sich die Rechte dann
getrennt widerrufen lassen.

Bedienung

Ziel Wie
Sofort prüfen statt auf den nächsten Lauf warten GitHub → Actions → „Promote ENTW to main“ → Run workflow
Einen entw-Commit von der Promotion ausnehmen [entw-only] in die Commit-Nachricht
Alles bis zu einem Stand als „erledigt“ markieren git tag -f entw-promoted <sha> && git push --force origin refs/tags/entw-promoted
Neu beginnen Tag löschen (git push origin :refs/tags/entw-promoted); dann gilt wieder der Merge-Base

Gegenrichtung: main -> entw

sync-entw.yml (Logik: scripts/sync-entw.sh) merged main nach jedem
Push (Cron stündlich als Fallback) in entw, damit entw nicht hinter main zurückfällt.
Hat entw eigene Commits (Nicht-Merge-Commits, die main nach Patch-Id nicht hat und die noch nicht
per Tag entw-promoted übergeben sind), passiert nichts: dort wird gerade getestet. Ein Merge-Konflikt lässt
den Lauf rot enden, ohne zu pushen.

Ziel Wie
Sync anhalten (z. B. längerer Test) Repo-Variable ENTW_SYNC_PAUSED=true setzen, zum Fortsetzen löschen
Sofort synchronisieren Actions → „Sync main into ENTW“ → Run workflow

Bewusst nicht enthalten

Auslöser: Push-Trigger plus Cron-Fallback

Ein push-Workflow läuft mit der Workflow-Datei des gepushten Branches, die Arbeit selbst
soll aber immer mit den aktuellen Workflows von main laufen. Deshalb gibt es zwei Auslöser:

Die Rulesets auf entw

Für entw gelten drei aktive Rulesets (entw-1: kein Löschen, kein Force-Push; entw-2: nur per PR,
Admin-Bypass; Protect MAIN: PR-Pflicht ohne Bypass). Weil die Regeln aller Rulesets gelten und ein Bypass
nur die Regeln seines eigenen Rulesets aufhebt, kommt jeder Commit auf entw per PR, auch von Admins. Die
Pipeline pusht nie auf entw, sie liest nur. Force-Push betrifft ausschließlich den Tag
entw-promoted und die Branches promote/entw-*, die von keinem Ruleset
erfasst sind.

Was getestet wurde

Lokal an einem Wegwerf-Repo (bare origin + Arbeitskopie, gh-Aufrufe im
Trockenlauf): Erkennen neuer Commits, Cherry-Pick über den Layout-Umzug
workloads/ → tech/, Überspringen von [entw-only], Umlegen des Tags,
„nichts Neues“ im zweiten Lauf, Draft-Warnung bei Neuanlage im alten Layout,
Konfliktfall (Issue, Tag unverändert, Exit 1). Später ergänzt und getestet: Commits, die nur
argocd/apps/entw/ ändern, werden übersprungen; ein gemischter Commit wird übernommen, sein
ENTW-Anteil bei Konflikt verworfen. actionlint und shellcheck sind sauber. Noch nicht gelaufen ist der Workflow auf GitHub selbst (PAT,
gh pr create, der workflow_call von ci.yml): der erste Lauf sollte per
Run workflow beobachtet werden.


Fehlersuche

Alle Skripte, Meldungen und Umgebungsvariablen: f00c0: Promotion.

gh workflow run promote-entw.yml -R pkr-lab/capulus-core        # sofort prüfen
gh run list -R pkr-lab/capulus-core --workflow promote-entw.yml
gh issue list -R pkr-lab/capulus-core --label entw-promotion
git fetch origin && git log origin/entw --oneline -5
git tag -l entw-promoted && git rev-parse entw-promoted
Symptom Ursache Lösung
Kein PR nach einem Push auf entw detect findet keine neuen Commits oder es gibt ein offenes entw-promotion-Issue Issue lesen und beheben, neuer Push startet neuen Versuch
Issue „ENTW-CI rot bei …“ CI auf entw fehlgeschlagen Fehler auf entw beheben, pushen (f0070)
Issue „ENTW -> main: Konflikt bei …“ Cherry-Pick-Konflikt in Dateien außerhalb von argocd/apps/entw/ Änderung von Hand nach main, Tag entw-promoted setzen oder [entw-only] in die Commit-Nachricht
GH_TOKEN fehlt Secret RENOVATE_TOKEN (PROMOTE_TOKEN) fehlt Secret anlegen
PR bleibt im Entwurf („altes Layout“) Commit legt Dateien in argocd/apps/platform|workloads/ an nach tech/ oder prod/ verschieben
PR löst keine CI aus PR wurde mit GITHUB_TOKEN erstellt PAT verwenden
entw bleibt hinter main zurück sync-entw wartet auf eigene, nicht übergebene Commits offene Promotion abschließen
Gleiche Änderung kommt mehrfach Tag entw-promoted nicht bewegt Befehl aus dem Issue ausführen

Allgemeine Fehlersuche: zentrale Fehlersuche.