Automatisierung

Was nach einem Merge auf main von allein passiert, und wie du jeden Schritt von Hand auslöst, wenn du musst.

Wie du Inhalte schreibst, steht unter Redaktion.

Der Ablauf

Werktags 06:00 Uhr (Europe/Berlin)
  └─ sync:changelog liest die CHANGELOG.md aus sechs Repositories
       ├─ nichts Neues  ->  Ende, kein Commit
       └─ etwas Neues   ->  Commit auf main
                              │
Push auf main ────────────────┘
  ├─ deploy:production   Doku nach Vercel deployen
  └─ notify:slack        Meldung in #guppy, wenn es etwas zu melden gibt

Das Deployment liegt vor der Meldung. GitLab überspringt eine Stage, wenn eine frühere gescheitert ist, also unterbleibt die Meldung, wenn das Deployment schiefgeht. Sonst würde eine Nachricht mit toten Links im Kanal landen.

Eine Schleife ist ausgeschlossen: sync:changelog läuft ausschließlich auf einem Zeitplan, und notify:slack pusht nie.

Was eine Meldung auslöst

Änderung	Meldung
Neue Datei in docs/news/	ja
Release mit neuer Minor- oder Major-Nummer	ja
Release mit Breaking changes	ja, unabhängig von der Versionsnummer
Zurückgezogenes Release	ja
Release-Kandidat, etwa 2.8.0-rc1	ja, mit #ReleaseCandidate
Reines Patch-Release	nein, wird in einer Zeile mitgezählt
Geänderter bestehender Beitrag	nein, nur neue Dateien zählen

Alles aus einem Push wird zu einer Nachricht zusammengefasst, nie eine pro Release.

Der wichtigste Punkt für dich als Entwickler: ein echter Breaking Change gehört unter die Überschrift Breaking changes, auch bei einem Patch. Diese Überschrift entscheidet, ob gemeldet oder still mitgezählt wird.

Die drei Jobs

Alles steht in .gitlab-ci.yml.

Job	Läuft wann	Tut was
sync:changelog	nur auf Zeitplan	Changelogs einlesen, bei Änderung committen und pushen
deploy:production	Push auf main	vercel deploy --prod
notify:slack	Push auf main	Digest in #guppy

Warum nicht die Git-Integration von Vercel

Vercel ordnet einen Push dem Vercel-Konto hinter dem Commit-Autor zu. Das betreffende Konto ist nur Betrachter im Team, deshalb wurden diese Deployments abgelehnt. Das Deployment aus der Pipeline umgeht die Zuordnung und nutzt ein Token eines Kontos, das deployen darf. Die Git-Integration ist inzwischen getrennt, GitLab ist die einzige Quelle.

Manuell

Changelog einsammeln

npm run changelog:sync

Schreibt docs/.vitepress/data/changelog.json. Braucht GUPPY_GITLAB_TOKEN in .env.local.

Wenn sich nichts geändert hat, bleibt die Datei byteweise identisch, auch das Feld generatedAt. Ein leerer git diff heißt also verlässlich: nichts Neues. Genau darauf stützt sich der Zeitplan-Job.

Meldung vorher ansehen

node scripts/notify-slack.mjs --dry-run
node scripts/notify-slack.mjs --dry-run --since <commit>

Gibt die fertige Slack-Nachricht als JSON aus und verschickt nichts. Ohne gesetztes Token verschickt das Skript ohnehin nie etwas, ein lokaler Lauf kann also nicht aus Versehen posten.

Das JSON lässt sich direkt in den Block Kit Builder von Slack einfügen, wenn du sehen willst, wie es gerendert aussieht.

Deployen

npx vercel deploy --yes          # Vorschau
npx vercel deploy --prod --yes   # Produktion

Im Normalfall brauchst du das nicht, die Pipeline macht es. Nützlich, wenn du etwas vor dem Merge zeigen willst.

Zeitplan von Hand starten

Build, Pipeline schedules, auf Play beim Eintrag Nightly changelog sync. Läuft sofort, sonst identisch zum nächtlichen Lauf.

Pipeline auf einem Branch testen

Eine Pipeline mit der Variable SLACK_NOTIFY_TEST auf 1 starten. Dann läuft notify:slack auch außerhalb von main, als manueller Job.

Achtung: die Slack-Variablen sind protected, erreichen also nur geschützte Branches. Auf einem normalen Feature-Branch läuft der Job durch, findet kein Token, gibt die Nachricht nur aus und wird grün. Das sieht nach Erfolg aus, hat aber nichts verschickt.

Variablen

Alle unter Settings, CI/CD, Variables des Projekts guppy-docs, jeweils masked und protected.

Variable	Wofür
GUPPY_GITLAB_TOKEN	Changelogs der anderen Projekte lesen
GUPPY_PUSH_TOKEN	Commit auf main pushen, braucht Rolle Maintainer
VERCEL_TOKEN	Deployment, Nutzer-Token mit Scope auf das Team
SLACK_BOT_TOKEN	Nachricht senden, Scope chat:write
SLACK_CHANNEL	Ziel-Kanal, als ID stabiler als als Name

Werte gehören nirgendwo ins Repository. .env.local ist für lokale Läufe da und steht in .gitignore.

Fehlersuche

Symptom	Ursache
Job grün, aber nichts in Slack	Kein Token erreichbar, meist protected auf ungeschütztem Branch. Steht im Log
invalid_auth	Slack-Token falsch oder zurückgezogen
not_in_channel	App nicht im Kanal. /invite @Guppy Docs, oder Scope chat:write.public
Could not retrieve Project Settings	Vercel-Token hat falschen Scope. Es muss ein Nutzer-Token mit Scope auf das Team sein
Zeitplan pusht nicht	GUPPY_PUSH_TOKEN fehlt die Rolle Maintainer. main ist geschützt
Nichts gemeldet, obwohl Release da	Patch ohne Breaking changes. So gewollt

Das Skript meldet jeden Slack-Fehler im Klartext samt Hinweis, was zu tun ist. Der Job-Log ist also die erste Anlaufstelle, nicht das Rätselraten.