600a0 - CI-Workflows, Skripte und Lint — Hintergründe
Quelle: pkr-lab/pkr-lab-docs/capulus/capulus-core/6-hintergruende/600a0-ci-workflows-und-skripte.md
CI-Workflows, Skripte und Lint — Hintergründe
Begründungen zu .github/workflows/, .github/dependabot.yml, scripts/, Makefile, .ansible-lint und .yamllint. Beschreibung, Einrichtung und Betrieb:
f0020, f0060, f0070,
f0080, f0090,
f00a0, f00b0,
d0080.
Übersicht dieser Kategorie: 60000.
Immer wiederkehrender Grund für ein PAT: PRs, Pushes und Merges mit dem Standard-GITHUB_TOKEN lösen keine weiteren Workflows aus. Ohne PAT bliebe die CI auf einem vom Workflow geöffneten
PR aus, und der Pflicht-Check würde ewig auf „pending“ stehen. Deshalb brauchen build-images, promote-entw, sync-entw und die Promotion-Kette ein PAT (Repo-Secret PROMOTE_TOKEN, ersatzweise
RENOVATE_TOKEN, jeweils mit Contents / Pull requests / Issues / Workflows = Read and write). Ein workflow_dispatch mit dem Standard-Token ist dagegen erlaubt und löst andere Workflows aus.
Workflows
| Workflow | Hintergrund |
|---|---|
ci.yml |
Pflicht-Gate auf jedem PR gegen main (die Jobs sind die „Required checks“ des main-Rulesets, f0090) und Nachkontrolle bei jedem Push nach main. Zusätzlich wiederverwendbar (workflow_call): promote-entw.yml ruft ihn mit ref: entw auf, um den Branch entw mit denselben Prüfungen freizugeben, bevor ein PR nach main entsteht. Historie: make lint existierte lange nur lokal, ein kaputtes Manifest fiel erst beim ArgoCD-Sync gegen den Live-Cluster auf (40080, Baustein 6). inputs.ref steht in der Concurrency-Gruppe: Der Aufruf aus promote-entw.yml (Branch entw) darf einen laufenden CI-Lauf auf main weder abbrechen noch blockieren. Go-Module werden per git ls-files gefunden statt fest verdrahtet, damit der Job auch auf dem Branch entw (anderes Ordner-Layout) und für künftige Go-Dienste ohne Änderung greift. Anlass: Ein Renovate-Merge (geoip2-golang v1 → v2) machte pacmans go.mod kaputt, ohne dass irgendetwas den Go-Code vor dem Image-Build übersetzte. Der Job token register kam mit dem Token-Management aus 40090 dazu. |
token-watch.yml |
Täglicher, vom Cluster unabhängiger Cron (nur GitHub), der ops/token-register.yaml gegen Ablaufdaten prüft und bei 60/30/14/7/1 Tagen ein Issue mit Label token-expiry anlegt bzw. kommentiert — Hintergrund und Schwellen: 40090. Anlass war der stille Ablauf des Tailscale-Logins auf worker-0 (20030): Ein Datum in einer Markdown-Checkliste wird nicht von selbst wieder aufgeschlagen, ein rot werdender täglicher Workflow schon. Der Standard-GITHUB_TOKEN genügt fürs Anlegen/Schließen von Issues (anders als bei PRs löst das keine Folge-Workflows aus, siehe Hinweis oben zu PATs). Lediglich zwei Kategorien werden live statt nur aus dem Register geprüft, weil dafür schon Secrets vorhanden sind: GitHub-PATs mit Ablauf (Antwort-Header github-authentication-token-expiration auf GET /user, geprüft mit RENOVATE_TOKEN/PROMOTE_TOKEN) und stellvertretend ein Tailscale-Gerät (TS_OAUTH_CLIENT_ID/TS_OAUTH_SECRET, client_credentials-Grant gegen die Tailscale-API, Knoten worker-0). Fehlt ein Secret oder reicht dessen Scope nicht, fällt die Prüfung geräuschlos auf das Register-Datum zurück. |
image-scan.yml |
Wöchentlicher, nicht blockierender Trivy-Scan der Images aller Charts (Montag 05:30 UTC, auch manuell). Bewusst kein Pflicht-Check und keine Fehlerschwelle: Die Funde stecken überwiegend in den Basis-Paketen der Upstream-Images (Incident-Befund), ein roter Merge-Check wäre dauerhaft rot. Das Ergebnis steht in der Job-Zusammenfassung. |
build-images.yml |
Baut und pusht die drei selbst gebauten Workload-Images (pacman, carplay-api, n8n) nach GHCR, sobald sich ihr Build-Kontext auf main ändert. Ersetzt den früheren manuellen Schritt argo submit --from workflowtemplate/kaniko-build-push. Auf PRs läuft derselbe Build ohne Push: Dockerfile und Go-Code müssen vor dem Merge bauen, ein kaputter Renovate-Bump fiel sonst erst nach dem Merge im Image-Build auf. Kein Required-Check, weil der Pfadfilter den Workflow bei PRs ohne Image-Änderung gar nicht startet. Nach dem Push öffnet der Lauf einen PR, der image.tag in der values.yaml der App setzt (scripts/bump-image-tag.py, Branch bump/<app>-image). Es wird nichts direkt auf main committet: Der PR läuft durch die Pflicht-Checks und wird von Hand gemergt (Merge = Rollout in TECH). Ohne PAT bleibt es beim Hinweis im Job-Summary und der Tag wird von Hand eingetragen. Concurrency: Ein Push auf main wird nie abgebrochen (ein halb gepushtes Image wäre schlimmer), bei einem PR macht ein neuer Push den alten Probebuild überflüssig. Gate je App: Der paths-Filter auf Workflow-Ebene entscheidet nur, ob der Lauf überhaupt stattfindet, nicht welche der drei Matrix-Apps sich geändert hat. Ohne das Gate würde das Ändern nur von pacmans Dockerfile auch carplay-api und n8n neu bauen. |
release.yml |
Jeder Push auf main (jeder gemergte PR) wird von semantic-release analysiert. Rechtfertigen die Commits seit dem letzten Tag ein Release (feat/fix/BREAKING CHANGE nach Conventional Commits), vergibt er die neue Version und veröffentlicht ein GitHub-Release mit generierten Notes, sonst passiert nichts. |
renovate.yml |
Fallback unabhängig von der Renovate-GitHub-App. Die App-basierte Einrichtung (f0020) hört still auf, PRs zu öffnen, sobald ihre Installation den Zugriff auf das Repo verliert (meist nach einem Wechsel des Repos zwischen persönlichem Konto und Organisation, weil die App im neuen Scope neu installiert werden muss). Der Workflow führt dieselbe renovate.json per renovatebot/github-action mit einem PAT aus, damit Updates weiterlaufen. Einrichtung: fine-grained PAT nur für dieses Repo (Contents / Pull requests / Issues / Workflows = Read and write) als Repo-Secret RENOVATE_TOKEN, sonst ist nichts zu konfigurieren. Der Cron läuft montags 05:00 UTC, vor dem Zeitplan „montags vor 6 Uhr Berliner Zeit“ in renovate.json. |
mirror-gitlab.yml |
Vollspiegelung (alle Branches und Tags, inklusive der semantic-release-Versionstags) auf ein GitLab-Remote, rein zur Redundanz (f0050). GitLab ist ein passives Backup-Ziel: Nichts wird je von GitLab zurückgepusht, und der Workflow überschreibt die Refs des GitLab-Projekts bei jedem Lauf per Force-Push, damit sie GitHub entsprechen. Die GitLab-Seite darf deshalb nie von Hand verändert werden. Zusätzlich läuft alle 6 Stunden ein Cron als Sicherheitsnetz, falls ein Push-Lauf verpasst wurde. |
promote-entw.yml |
Übergibt Änderungen vom Branch entw (Quelle des ENTW-Clusters) als PR an main, aber erst, wenn die CI auf entw grün ist (f0080). Ablauf: detect (gibt es entw-Commits, die seit dem Tag entw-promoted noch nicht an main übergeben wurden?) → ci (dieselben Prüfungen wie auf PRs, aber gegen ref=entw) → promote (Cherry-Pick der neuen Commits auf promote/entw-<sha> ab main, PR öffnen, Tag entw-promoted auf den geprüften Stand umlegen). Es ist ein Cron statt on: push: entw, weil ein push-Workflow mit der Workflow-Datei des gepushten Branches läuft: entw hat ein eigenes (älteres) Layout mit eigener ci.yml. Der Cron auf main ist davon unabhängig. |
entw-trigger.yml |
Startet die Promotion sofort, wenn auf entw gepusht wird, statt auf den Cron zu warten: GitHub drosselt Schedules (im Test lief der 15-Minuten-Cron nur ca. alle 2–5 Stunden). Ein push-Workflow läuft mit der Datei des gepushten Branches, diese Datei wirkt also erst, wenn sie auf entw liegt (kommt mit dem nächsten Merge main → entw). Der Job tut selbst nichts außer einem workflow_dispatch auf main, die Arbeit macht weiter promote-entw.yml mit den aktuellen Workflows von main. |
sync-entw.yml |
Hält entw auf dem Stand von main: Nach jedem Push auf main wird main in entw gemergt, außer entw hat eigene, noch nicht übergebene Commits (dort wird gerade etwas getestet). Dann bleibt entw unverändert, bis die Promotion die Commits nach main übergeben hat oder der Test-Branch aufgeräumt ist. Pause per Hand: Repo-Variable ENTW_SYNC_PAUSED=true (Settings → Variables). entw ist per Ruleset geschützt (PR-Pflicht, kein Bypass), der Workflow öffnet deshalb einen PR main → entw und aktiviert Auto-Merge (gh pr merge --auto). Die Repo-Einstellung „Allow auto-merge“ muss aktiv sein, und das PAT ist nötig, weil entw-trigger.yml sonst stumm bliebe. Ein stündlicher Cron (Minute 17) dient als Fallback, falls ein Push-Lauf ausgefallen ist. |
promote-chain.yml |
Übernimmt Versionen (image.tag, Chart-Abhängigkeiten) entlang ENTW → TECH → PROD, sobald sie das Gesundheits-Gate bestehen (≥ 24 h gesund auf ENTW, danach ≥ 2 h gesund auf TECH, 60030). Ergebnis sind PRs nach main (TECH: optional Auto-Merge, PROD: immer manuelles Review). Logik in scripts/promote-chain.py, Konfiguration in argocd/promotion.yaml. Der Runner tritt per Tailscale dem Tailnet bei und fragt beide ArgoCD-Instanzen ab (ENTW: eigene Instanz auf entw-vm über die Subnet-Route des Homeservers, TECH/PROD: Hub-ArgoCD). Solange die Secrets ARGOCD_ENTW_TOKEN/ARGOCD_HUB_TOKEN fehlen, macht der Lauf nichts. Beide Instanzen werden über das LAN-Subnetz (Subnet-Route des Homeservers) erreicht, ein einziger ACL-Grant auf 192.168.178.94 und .100 (Port 30080) genügt. |
tailscale-poc.yml |
Diagnose für die Promotion-Kette, nur manuell startbar: Erreicht ein GitHub-Runner über Tailscale die beiden ArgoCD-Instanzen und die ENTW-Apps? Der Lauf testet jeden Weg einzeln, gibt eine Tabelle aus und schlägt erst am Ende fehl, wenn ein für die Promotion nötiger Weg nicht funktioniert. Wege (ArgoCD per HTTPS über den Traefik-Ingress, Zertifikat gegen pki/homeserver-root-ca.pem): hub-lan (argocd.tech.homeserver, Grant auf 192.168.178.94:443, nötig), entw (argocd.dev.homeserver, nur per Subnet-Route, Grant auf 192.168.178.100:443, nötig), smoke (ENTW-Ingress mit Host whoami.dev.homeserver für Smoke-Tests, Grant auf 192.168.178.100:80, optional), hub (Hub über die Tailnet-Adresse, TCP-Probe auf tag:tech-node:443, nur Diagnose). |
codeql.yml |
Erweiterte Einrichtung statt „Default setup“ in den Repo-Einstellungen: Sprachen, Build-Schritte und Trigger sind versioniert und per PR änderbar wie alles andere im Repo, und nur so lässt sich das Xcode-Projekt vor der Swift-Analyse erzeugen. Beides zusammen geht nicht, mit aktivem Default setup weist GitHub die Uploads des Workflows ab. Go mit autobuild: lokal mit CodeQL 2.26.2 geprüft, der Autobuilder findet beide go.mod ohne go.work und extrahiert alle 17 Go-Dateien; ein eigener Build-Schritt je Modul ist nicht nötig. Er läuft ohne setup-go, die go-Direktive in go.mod holt die passende Toolchain selbst. Swift mit autobuild: Der Autobuilder von CodeQL ruft xcodebuild mit genau den Schaltern auf, die die Extraktion braucht (CODE_SIGNING_ALLOWED=NO, ohne Compile-Cache und mit SWIFT_USE_INTEGRATED_DRIVER=NO), ein selbst geschriebener xcodebuild-Aufruf müsste diese Liste nachpflegen. Er braucht aber ein .xcodeproj, das nicht eingecheckt ist (ios/.gitignore, 60080); deshalb erzeugt XcodeGen es vor init. Swift-Analyse geht nur auf macOS, für öffentliche Repos kostenlos. Der Schritt ist lokal nicht testbar (kein Mac); scheitert er, ist der Ausweg build-mode: manual (siehe Troubleshooting in d0080). Keine Konfigurationsdatei: Der einzige Kandidat wäre ein paths-ignore für das vendorte jquery-1.10.2.min.js gewesen, aber der JavaScript-Extraktor überspringt **/*.min.js und **/*-min.js schon von sich aus (Basis-Konfiguration des Extraktors, lokal geprüft). Standard-Abfragesatz statt security-extended: gemessen 2 gegen 46 Funde, die 44 zusätzlichen sind überwiegend Fehlalarme (30× go/log-injection auf slog-Attribute, die slog selbst maskiert; 6× actions/untrusted-checkout/medium auf den rechtelosen ci.yml). paths-ignore nur für pull_request: Reine Doku-PRs sparen die fünf Jobs; auf main läuft CodeQL bei jedem Push, damit jeder PR eine Analyse seines Basis-Commits zum Vergleich hat. persist-credentials: false, weil CodeQL keine Git-Zugangsdaten braucht. Kein Pflicht-Check, Begründung in f0090. |
security-issues.yml |
Weder CodeQL noch Dependabot legen Issues an, beide schreiben nur in den Security-Tab, den man aktiv aufrufen muss. Ein Issue dagegen benachrichtigt und steht in derselben Liste wie alle anderen Aufgaben (dasselbe Motiv wie bei token-watch.yml: was nicht von selbst wieder auftaucht, wird vergessen). Täglicher Cron statt workflow_run nach CodeQL: Dependabot-Alerts entstehen unabhängig von jedem Workflow (neue Advisory, neuer Push), ein Zeitplan erfasst beide Quellen. workflow_run gilt außerdem als riskanter Trigger (läuft im Kontext von main mit Zugriff auf die Secrets, auch wenn ein PR aus einem Fork den auslösenden Lauf gestartet hat) und hätte nur Stunden gespart. Nur GITHUB_TOKEN: vulnerability-alerts: read gibt es erst seit 2026-09-03; vorher hätte das Lesen der Dependabot-Alerts ein weiteres PAT gebraucht, eines mehr für das Token-Register. actionlint 1.7.12 kennt die Berechtigung noch nicht und meldet sie als unbekannt, GitHub akzeptiert sie. Rot statt still, wenn eine Quelle nicht abrufbar ist (z. B. Dependabot-Alerts im Repo aus): Ein grüner Lauf ohne Dependabot-Daten sähe aus wie „keine Lücken“. Die Schwelle MIN_SEVERITY steht als env in der Datei statt als Repo-Variable, damit eine Änderung per PR nachvollziehbar bleibt. |
Tailscale-Action: Der Workflow meldet sich per Federated Identity an (TS_OAUTH_CLIENT_ID/TS_AUDIENCE, Tag tag:ci, id-token: write im Job). Es liegt kein dauerhaftes Secret in GitHub: Der Runner
tauscht ein kurzlebiges GitHub-OIDC-Token bei Tailscale, die Credential gilt nur für repo:pkr-lab/capulus-core:ref:refs/heads/main (Incident 015, einen gestohlenen OAuth-Secret-Wert gäbe es nicht). Die Action erzeugt pro Lauf einen frischen, kurzlebigen Key. Ein Auth-Key
wäre einmalig oder läuft ab (max. 90 Tage) und ließ den Beitritt still scheitern. Die Action nimmt Subnet-Routen selbst an (--accept-routes): Das LAN-Subnetz 192.168.178.0/24 (u. a. ENTW-VM) kommt vom
Homeserver. Kein zusätzliches args: --accept-routes setzen: Ein doppeltes Flag bricht tailscale up mit „flag provided multiple times“ ab, ohne dass die Action fehlschlägt. Der Schritt wird grün und
der Beitritt fehlt (f00a0).
Aktion mattermost-notify
- Karte statt Klartext. Die Aktion sendet ein Message-Attachment mit leerem
message. Farbbalken jestatus, verlinkter Titel, Felder und Footer machen Erfolg und Fehler auf einen Blick unterscheidbar, die Farben entsprechen denen der Mails aus „Publish: Benachrichtigung“ (30070). Dasfallback-Feld (Titel plus Text) liefert den lesbaren Text für Push-Benachrichtigungen und Vorschauen. - Alte Aufrufe bleiben gültig.
title,status,linkundfieldssind optional,messagebleibt Pflicht. Ohne Titel entsteht nur Farbbalken, Text und Footer. fieldsist ein JSON-String. Inputs zusammengesetzter Aktionen sind immer Strings, verschachtelte Werte gehen nur serialisiert. Die Aktion prüft das JSON mitjqund verwirft Ungültiges, damit ein Tippfehler im Aufrufer keine Meldung verhindert.- Der „Lauf ansehen“-Link steckt im Titel. Ohne
linkzeigt der Titel auf den aktuellen Lauf, die Aufrufer müssen keine eigene Link-Zeile mehr bauen.release.ymlsetztlinkauf das Release. - Nie rot wegen Mattermost. Ein Sendefehler ist nur eine Warnung. Eine Benachrichtigung darf den Lauf nicht scheitern lassen, den sie melden soll.
Skripte
promote-entw.sh und sync-entw.sh
Beide sind die Logik hinter den gleichnamigen Workflows und kennen DRY_RUN=1 (überspringt alle gh-Aufrufe bzw. öffnet keinen PR, für lokale Tests).
promote-entw.sh hat drei Teilbefehle: detect (gibt head, base und changed aus, in GITHUB_OUTPUT, sonst stdout), promote (Cherry-Pick der neuen entw-Commits auf einen Branch ab main, PR öffnen, dann
den Tag umlegen) und report-ci-failure (meldet ein rotes CI auf entw als Issue).
- Der Tag
entw-promotedist die Marke „bis hierhin wurdeentwanmainübergeben“. Er wandert erst nach erfolgreich geöffnetem PR (oder nach „nichts zu übergeben“) auf den neuenentw-Stand und existiert erst
nach der ersten Promotion. „Neue Commits“ ist alles zwischen Tag undentw-Spitze, das nicht schon inmainist. Ohne Tag (erster Lauf) gilt der Merge-Base vonmainundentw. - Die Reihenfolge ist alt → neu, ohne Merge-Commits und ohne alles, was
mainschon hat (z. B. kommen nach einem Mergemain→entwdiemain-Commits nicht doppelt zurück). - Nicht übernommen wird ein Commit, wenn er
[entw-only]trägt oder ausschließlichargocd/apps/entw/ändert. Solche Änderungen gehen über die Promotion-Kette (Versionen nach 24 h Gesundheit als PR nach
tech/prod), ein Cherry-Pick des ENTW-Ordners nachmainwäre nur Rauschen (TECH und PROD lesen ihn nie). - Konflikt nur in
argocd/apps/entw/(typisch: Ein Vorgänger-Commit im ENTW-Ordner wurde übersprungen): Der ENTW-Anteil wird verworfen, der Rest des Commits übernommen. Neue Dateien im alten Layout
(platform/workloads) haben aufmainkeinen Platz mehr (tech/prod): Cherry-Pick erkennt Umzüge bestehender Dateien, aber keine Neuanlagen. - Ein offenes Issue mit der Kurz-SHA im Titel bedeutet: Für diesen
entw-Stand ist bereits Bescheid gegeben (Konflikt oder rotes CI), es wird nicht erneut versucht. So prüft der Cron nicht denselben Stand alle 15 Minuten neu.
sync-entw.sh hält entw auf dem Stand von main, solange entw keine eigenen Commits hat.
- Eigene Commits sind Nicht-Merge-Commits auf
entw, diemaininhaltlich nicht hat (git cherry, also nach Patch-ID: Ein nachmainübergebener Cherry-Pick zählt nicht) und die noch nicht mit dem Tag
entw-promotedübergeben wurden.entwhat eigene Commits (es wird gerade dort getestet) → nichts tun.entwenthält schon alles ausmain→ nichts tun. Sonst wirdmaininentwgemergt. - Das Ruleset auf
entwverlangt Pull Requests (keine Bypass-Actors). Statt direkt zu pushen, wird ein PRmain→entwgeöffnet und per Auto-Merge mit Merge-Commit (kein Squash) gemergt, damitmaindanach
Vorfahre vonentwbleibt.--autowartet auf die Pflicht-Checks. Sind keine (mehr) offen, lehntghdas mit „clean status“ ab, dann wird direkt gemergt. Ein Merge-Konflikt bricht mit Fehler ab, der Lauf wird
rot undentwbleibt unverändert.
Weitere Skripte
| Skript | Hintergrund |
|---|---|
promote-chain.py |
Die Feldliste für die ArgoCD-API wurde gegen die echte API getestet: items.status.health liefert health komplett, für sync müssen die Unterfelder einzeln genannt werden (items.status.sync allein liefert nichts). |
promotelib.py |
Versionen sind exakte Chart-/Image-Versionen, keine Bereichsausdrücke. |
setup-main-ruleset.sh |
Legt das Ruleset „main: PR + CI“ an bzw. aktualisiert es: main nur per Pull Request, dazu die CI-Jobs aus ci.yml als Pflicht-Checks (--dry-run zeigt das JSON, gh muss als Admin angemeldet sein). Erst ausführen, wenn ci.yml mit den vier Jobs schon auf main liegt, sonst verlangt das Ruleset Checks, die es nirgends gibt, und jeder PR bleibt ewig auf „pending“. Die Namen im Skript müssen dem name: der Jobs in ci.yml entsprechen. Danach gibt es keinen Direkt-Push auf main mehr, auch nicht für den Admin. Notausgang: Als Repo-Admin kann ein PR trotz roter oder fehlender Checks gemergt werden (bypass_mode: pull_request), gedacht für den Fall, dass die CI selbst kaputt ist. |
create-argocd-ci-token.sh, reseal-for-prod.sh, seal-github-token.sh |
Siehe 60030. |
seal-alert-caller.sh |
Versiegelt das SIP-Passwort des Telefon-Alarms und schreibt es in argocd/apps/tech/alert-caller/values.yaml. Das Skript ersetzt einen früheren Wert und lehnt Passwörter mit ;, " oder Leerzeichen ab, weil der Caller daraus die baresip-Kontozeile baut. Der Aufruf per einzelnem Skript statt als Mehrzeilen-Befehl vermeidet Fehler beim Einfügen (10020). |
seal-ntfy-tokens.sh |
Versiegelt den publisher_token für ntfy-bridge und alamos-apager und den reader_token für carplay-api (je Namespace und Secret-Name, strikter Scope) und schreibt sie samt enabled: true in die jeweilige values.yaml. Die Tokens kommen aus der Credentials-Datei (NTFY_CREDENTIALS, Standard ~/ntfy-credentials-2026-10-17.txt) und werden nie ausgegeben. Siehe 10010. |
seal-alert-caller-token.sh |
Versiegelt den Telefon-Alarm-Token aus ~/alert-caller-token-2026-10-17.txt (ALERT_CALLER_CREDENTIALS) für alert-caller/alert-caller-secrets und monitoring/alert-caller-token und trägt beide in die values.yaml ein (Alertmanager-Secret mit enabled: true). Ein vorhandener Wert wird ersetzt, der Token wird nie ausgegeben. Siehe 10020. |
check-doc-links.py |
Prüft relative Links und Anker in allen Markdown-Dateien (f0070). |
check-token-register.py |
Die Vollständigkeitsprüfung sucht SealedSecret-Dateien selbst per Regex auf ^kind:\s*SealedSecret\s*$, statt sie mit yaml.safe_load zu parsen: Die Helm-Templates enthalten Go-Template-Ausdrücke ({{ … }}) und sind kein gültiges YAML. Pfade mit /bootstrap (die beiden ApplicationSet-ignoreDifferences-Filter in argocd/bootstrap*/applicationset.yaml) sind bewusst ausgenommen — sie referenzieren nur die Ressourcenart, sind aber selbst keine SealedSecrets. issued darf im Register null sein: Beim Einführen des Registers war das echte Anlegedatum der meisten Secrets nicht mehr bekannt, ein erfundenes Datum wäre falsche Sicherheit. Ohne issued bleibt ein Eintrag ohne festes expires einfach unbeobachtet, bis die nächste Rotation das Datum eintraegt — ehrlicher als ein geschätztes Datum. max_age_days ist Pflicht und eine Rotationsfrist wird nur geprüft, wenn issued bekannt ist: Ein erfundenes Anlegedatum würde falsche Sicherheit liefern, deshalb meldet das Skript unbekannte Alter nur als Hinweis und lässt die CI nicht scheitern. Die Frist wird gegen das heutige Datum geprüft, ein Eintrag wird damit ohne Commit rot, sobald seine Frist verstrichen ist. |
token-watch.py |
Ein Issue pro Token-id, gefunden per gh issue list --search (Titel-Suche statt Label allein, weil mehrere Tokens gleichzeitig fällig sein können). Ein HTML-Kommentar <!-- token-watch:threshold=N --> im Issue-Body hält die zuletzt gemeldete Schwelle fest: Ohne ihn würde der tägliche Lauf bei „45 Tage übrig“ jeden Tag neu kommentieren, statt nur beim Wechsel 60→30→14→7→1. Der Issue-Body selbst wird bei jedem Lauf aktualisiert (aktueller Tage-Stand), auch wenn keine neue Schwelle erreicht ist — nur der Kommentar (= Benachrichtigung) unterbleibt dann. Ein offenes Issue schließt sich automatisch, sobald sein id in einem Lauf nicht mehr unter den fälligen Tokens auftaucht (rotiert oder Ablaufdatum verlängert) — dieselbe Idempotenz-Idee wie bei promote-chain.pys sticky_issue. |
security-issues.py |
Ein Issue je Gruppe statt je Alert: Code-Scanning-Alerts je Werkzeug und Regel, Dependabot-Alerts je Manifest. Ende September 2026 hätte carplay-api/src/go.mod allein rund 28 Dependabot-Alerts gebracht (govulncheck-Abschätzung), also 28 Issues für einen einzigen Fix-PR; die Gruppierung je Manifest entspricht genau den gruppierten Dependabot-PRs (groups in dependabot.yml), und gleichartige Code-Funde behebt man meist mit demselben Muster. Zuordnung über HTML-Kommentare im Body (<!-- security-issues:key=… -->, <!-- security-issues:alerts=… -->) statt über die Issue-Suche: Die Suche wird verzögert indexiert, ein frisch angelegtes Issue wäre beim nächsten Lauf eventuell noch nicht auffindbar. Das Skript liest deshalb alle Issues mit dem Label security (auch geschlossene, für das Wiederöffnen) und wertet die Marker selbst aus; Issues ohne Marker (von Hand angelegt) bleiben unberührt. Die Liste der bekannten Alert-Nummern sorgt dafür, dass nur neue Alerts einen Kommentar und damit eine Benachrichtigung auslösen, ein bloß kleiner gewordener Fund nicht. Wiederöffnen statt Respektieren eines manuellen Schließens: Die Wahrheit ist der Alert-Status. Zwei Wege zum „Ignorieren“ (Alert verwerfen und Issue schließen) würden auseinanderlaufen, deshalb gibt es nur einen, das Verwerfen im Security-Tab mit Begründung. Das Skript schließt selbst immer mit Grund completed. Schließen nur für erfolgreich gelesene Quellen: Schlägt das Lesen der Dependabot-Alerts fehl, wären sonst alle Dependabot-Issues „behoben“. Ein 404 no analysis found bei Code-Scanning ist dagegen kein Fehler, sondern der Zustand vor dem ersten CodeQL-Lauf. Kein Fremdtext aus dem Code im Issue: Die Meldungstexte der Alerts (sie zitieren Bezeichner und Werte aus dem Code) stehen nicht im Body, nur Regelname, Pfad, Zeile und Link; Advisory-Zusammenfassungen kommen aus der kuratierten GitHub Advisory Database, | und Zeilenumbrüche werden für die Tabelle entschärft. Dependabot-PRs werden über den Branch-Präfix dependabot/ und den Paketnamen im PR-Text gefunden; bei Go zusätzlich über das Verzeichnis, weil derselbe Paketname in mehreren go.mod stehen kann. Der Body wird nur geschrieben, wenn er sich geändert hat. Ohne Docstrings und Kommentare, wie der übrige Code. |
Dependabot und Renovate
.github/dependabot.yml: Dependabot ist hier nur für Sicherheits-PRs da, Versions-Updates macht Renovate (d0080).
open-pull-requests-limit: 0schaltet die Versions-Updates je Ökosystem ab; Sicherheits-PRs zählen laut GitHub nicht gegen dieses Limit. Dieschedule-Angabe ist trotzdem Pflichtfeld der Datei.- Gruppen mit
applies-to: security-updates: ein PR je Verzeichnis. Einzel-PRs je Paket würden sich bei Go gegenseitig blockieren: Nach jedem Merge ändert sichgo.sum, alle übrigen PRs müssten neu aufgebaut werden. - Explizite Verzeichnisse statt Glob (
directorieskönnte*): Ein Muster wie/argocd/apps/*/*/srcträfe auchpacman/src(Frontend ohnego.mod); die Liste nennt genau die beiden Module. Fehlt ein neues Modul in der Liste, kommen dessen Sicherheits-PRs trotzdem, nur ohne Gruppe und Labels. - Nur
gomodundgithub-actions: Für Docker-Images und Helm-Charts gibt es keine Dependabot-Alerts, also auch keine Sicherheits-PRs; npm- oder pip-Manifeste gibt es im Repo nicht (die npm-Pakete im n8n-Image installiert das Dockerfile direkt). commit-message.prefix: fixmitinclude: scopeergibtfix(deps): …: ein Sicherheits-Fix ist für semantic-release ein Patch-Release, Renovates Versions-Updates bleibenfeat(deps).- Kein
cooldown, obwohl zizmor es anmahnt: Es wirkt nur auf Versions-Updates, und die sind aus. Wer sie je einschaltet, sollte es ergänzen.
GitHub-Actions auf Commit-SHAs gepinnt (Incident 015, 2026-10-17): Alle uses: zeigen auf eine 40-stellige Commit-SHA statt auf einen Tag. Ein Tag lässt sich im
Action-Repository umbiegen (so geschehen bei tj-actions/changed-files 2025), die SHA nicht. Besonders wichtig sind die Actions, die Secrets bekommen:
tailscale/github-action (OAuth-Client mit auth_keys:write), renovatebot/github-action (PAT mit Schreibrechten), docker/login-action und docker/build-push-action
(Registry-Push) sowie gitleaks/gitleaks-action.
- Der Versions-Kommentar hinter der SHA (
# v7.0.1) ist die einzige Ausnahme von der Regel „keine Kommentare im Code“. Renovate und Dependabot lesen ihn, um den Pin auf die nächste
Version zu heben. Ohne ihn wüssten sie nicht, welcher Tag zur SHA gehört. - Gepinnt wurde auf die Commits, auf die die Tags am 2026-10-17 zeigten. Es ändert sich also kein Verhalten. Jede SHA wurde mit
gh api repos/<owner>/<repo>/commits/<tag>gegen den
semantischen Tag geprüft. - Renovate hält die Pins aktuell. Das Preset
helpers:pinGitHubActionDigestspinnt neue Actions beim nächsten Lauf selbst und aktualisiert SHA und Kommentar gemeinsam
(PR montags,feat(deps): …, mit CI). Dependabot (nur Sicherheits-PRs) arbeitet mit demselben Format. - Tailscale-Client fest auf
1.104.1stattlatest(inpromote-chain.ymlundtailscale-poc.yml).latesthätte jeden Lauf mit dem neuesten Client gestartet, eine kompromittierte
Release hätte also ohne Review im Runner mit Tailnet-Zugang gelaufen. Ein Regex-Manager inrenovate.json(customManagers) liest die Version hintertags: tag:ciund
schlägt neue Versionen vor; die RegelallowedVersionslässt nur Stable-Releases zu (gerade Minor-Nummer, Tailscale zählt ungerade Minor-Versionen als Unstable). - Nicht Teil dieses Schritts:
npx semantic-releaseundpip installohne feste Versionen in den Workflows (Incident 031).
renovate.json → vulnerabilityAlerts.enabled: false: Renovate liest für seine Sicherheits-PRs dieselben Dependabot-Alerts. Mit beiden aktiv gäbe es für jede Lücke zwei PRs, sobald Renovate Lesezugriff hat (die Renovate-App hat ihn, das PAT des Fallbacks bisher nicht). Dependabot gewinnt, weil er binnen Stunden reagiert, der Renovate-Fallback nur montags läuft.
Lint-Konfiguration
.ansible-lint passt den Linter an bestehende, absichtliche Repo-Konventionen an, statt hunderte etablierte Tasks und Variablen umzuschreiben:
- Task-Namen sind durchgehend deutsch und kleingeschrieben („ethtool installieren“ statt „Install ethtool“), etablierter Stil im ganzen Repo und keine versehentliche Inkonsistenz.
- Mehrere zusammengehörige Rollen teilen sich bewusst denselben Variablen-Präfix statt je einen eigenen Rollen-Präfix zu tragen (z. B.
semaphore_bootstrap,semaphore_secretsundsemaphore_targetsteilen sichsemaphore_*, weil
sie dieselben Werte querlesen). ansible-lints Default erwartet einen Präfix pro Rolle, das passt nicht zum tatsächlichen Design. - Einzelne Task-Namen haben ein Jinja-Fragment in der Mitte statt am Ende (z. B. „Assert inventory '{{ x }}' exists in project {{ y }}“), lesbarer so und kein Fehler.
- Echte (wenn auch kleine) Findings wurden direkt behoben statt geskippt:
no-changed-when(banana_pi_kiosk,cups_print_server),risky-shell-pipe(semaphore_secrets),no-handler(worker_apt_update).
.yamllint:
- Helm-Templates (
argocd/apps/*/*/templates/) und vendortecharts/sind ausgenommen: Sie enthalten Go-Template-Ausdrücke ({{ … }}), die yamllint teils alstruthy-/comments-Verstoß wertet. Die Regeln sind
hier bewusst entspannt, echte Fehler fängthelm lint/helm template. Alles andere unteransible/undargocd/wird gelintet. crds/(argocd/apps/*/*/crds/) ist ausgenommen: Die CRDs des capulus-operator sind von controller-gen erzeugt und unterscheiden sich in der Listeneinrückung von der yamllint-Vorgabe. Die Dateien werden nicht von Hand bearbeitet (600c0).comments-indentation: falseist nicht optional: ansible-lint verlangt diese Mindesteinstellungen von jeder eigenen yamllint-Config, sonst verweigert es seine YAML-Prüfung komplett („Found incompatible custom yamllint
configuration“).- Die Regel
empty-linesgilt weiter: Eine YAML-Datei endet mit genau einem Zeilenumbruch, eine Leerzeile am Dateiende ist ein Fehler.
CLAUDE.md und .gitignore
CLAUDE.md im Repo-Root hält die Arbeitsregeln für Claude Code (keine Kommentare im Code, Doku-Pflicht, Secrets nur als SealedSecret, lokale
Prüfbefehle der CI, Commit-Stil). Claude committet, pusht und öffnet PRs nicht selbst, sondern bereitet Änderungen nur vor; das Einchecken
bleibt beim Nutzer, damit nichts ungeprüft auf main und damit in TECH/PROD landet. Sie stand früher in .gitignore und wird jetzt versioniert, damit jede Session, auch in der Cloud-Sandbox mit
frischem Klon, dieselben Regeln lädt. AGENTS.md und .claude/ bleiben ignoriert, weil sie lokale, persönliche Einstellungen enthalten.
Ändert sich eine Konvention (neuer CI-Job, neue Kategorie in docs/, neuer Pflichtschritt beim Anlegen einer App), wird CLAUDE.md im selben PR
mitgezogen.
Secret-Muster in .gitignore: Private Schlüssel und Zugangsdatei-Typen sind ignoriert (*.pem, *.key, *.p12, *.pfx, id_rsa*, id_ed25519*, *.kdbx, .env, .env.*, kubeconfig*, *.kubeconfig, .vault_pass*, vault-password*, *.sqlite), damit ein git add . im Arbeitsverzeichnis sie nicht aufnimmt. Die öffentliche Root-CA ist als !homeserver-root-ca.pem ausgenommen (sie liegt in docs/assets/ und in zwei Charts unter files/). Das ist nur ein Netz gegen Versehen: git add -f umgeht es, und schon eingecheckte Dateien bleiben getrackt. Der eigentliche Schutz ist gitleaks in der CI. Braucht ein neues Zertifikat ins Repo (öffentliches Zertifikat, kein Schlüssel), kommt eine !-Ausnahme mit dem genauen Namen dazu.