Automatisierung
Quelle: pkr-lab/pkr-lab-docs/EDV-Kretzer/automatisierung.md
Automatisierung
Alle Abläufe rund um die Website: Deployment, Release-Verlauf, Status-Hinweis und die zugehörigen n8n-Workflows.
Code: .github/workflows/, scripts/build-releases.mjs, automation/
Überblick
| Workflow | Datei | Auslöser | Wirkung |
|---|---|---|---|
| Deploy to netcup | deploy.yml |
Push auf main, manuell, workflow_call |
Spiegel aktualisieren und nach httpdocs auschecken |
| Release-Verlauf | releases.yml |
stündlich (Minute 17), manuell | data/releases.json erzeugen, bei Änderung committen und deployen |
| Status-Hinweis | status.yml |
nur manuell (workflow_dispatch) |
data/status.json schreiben, committen, deployen |
| Release | release.yml |
Push auf main, manuell |
semantic-release (zentraler Workflow) |
| Commitlint | commitlint.yml |
Pull Request | Conventional Commits prüfen |
flowchart TD
push[Push auf main] --> deploy[deploy.yml]
cron[Cron stündlich] --> rel[releases.yml: build-releases.mjs]
rel -->|data/releases.json geändert| commit1[Commit chore releases skip ci]
commit1 --> deploy
man[Manueller Start oder n8n-Formular] --> st[status.yml: data/status.json]
st --> commit2[Commit chore status skip ci]
commit2 --> deploy
deploy -->|SSH| nc[netcup: git fetch und checkout -f main]
gh[GitHub-API capulus-core Releases] --> rel
Deployment
deploy.yml verbindet sich per appleboy/ssh-action mit dem netcup-Hosting und führt aus:
git -C "$HOME/git/EDV-Kretzer" fetch --prune origin
git --git-dir="$HOME/git/EDV-Kretzer" --work-tree="<NETCUP_PATH>" checkout -f main
Das Docroot ist kein Klon, sondern ein Arbeitsverzeichnis des Git-Spiegels. Einrichtung, Secrets (NETCUP_HOST, NETCUP_USER, NETCUP_SSH_KEY, NETCUP_PORT, NETCUP_PATH) und Stolperstellen: Installation. Die Gruppe deploy-netcup verhindert parallele Deployments, ein laufendes wird nicht abgebrochen (cancel-in-progress: false).
Die Commits aus releases.yml und status.yml tragen [skip ci] und werden mit dem GITHUB_TOKEN gepusht, ein Push-Lauf von deploy.yml entsteht daraus nicht. Deshalb rufen beide Workflows deploy.yml selbst auf (uses: ./.github/workflows/deploy.yml, secrets: inherit), releases.yml nur, wenn sich die Datei geändert hat.
Release-Verlauf
scripts/build-releases.mjs (Node, ohne Abhängigkeiten) schreibt data/releases.json:
- Ruft
https://api.github.com/repos/pkr-lab/capulus-core/releases?per_page=10ab. DerGITHUB_TOKENdes Workflows dient als Bearer-Token (ohne Token gilt das Rate-Limit für anonyme Aufrufe, 60 pro Stunde). Bei einer Antwort ≠ 200 endet das Skript mitGitHub-API: HTTP <n>und Exit-Code 1. - Verwirft Entwürfe und Vorabversionen, behält höchstens 10.
- Kurzfassung: aus den Release-Notes die Abschnitte
### Features(Präfix „Neu“) und### Bug Fixes(„Behoben“), je höchstens 3 Einträge, der Rest als „und N weitere“. Commit-Hash-Links am Zeilenende und**scope:**werden entfernt bzw. zuscope:umgeformt. Länge höchstens 320 Zeichen (…). Ohne passende Abschnitte: „Release veröffentlicht.“ tagistMajor(Release-Notes beginnen mit der Überschrift# [X.0.0]), sonstFeature(hat Abschnitt Features), sonstFix.- Titel und Text sind HTML-escaped (
&,<,>,"). Die Datei wird mit Zeilenumbruch am Ende geschrieben.
releases.yml committet nur, wenn sich data/releases.json geändert hat (git diff --quiet), mit chore(releases): Release-Verlauf aktualisiert [skip ci], macht git pull --rebase und git push, und deployt anschließend.
Lokal ausführen (ohne Commit):
GITHUB_TOKEN=$(gh auth token) node scripts/build-releases.mjs && git diff data/releases.json
Status-Hinweis
status.yml schreibt data/status.json mit jq aus den Eingaben, committet mit chore(status): Status-Hinweis aktualisiert [skip ci] und deployt.
| Eingabe | Wirkung in status.json |
|---|---|
aktiv |
active |
art |
level (maintenance, incident, info) |
titel |
title |
text |
message |
bereiche |
areas, Komma-getrennt, Leerzeichen entfernt, leere Einträge verworfen |
bis |
until (leer = offen) |
| – | since: aktuelle UTC-Zeit, nur bei aktiv |
Bei aktiv=false setzt der Workflow areas, since und until zurück. Hat sich nichts geändert, bricht der Commit-Schritt ohne Fehler ab (git diff --cached --quiet && exit 0), danach läuft trotzdem das Deployment. Bedienung: Nutzung, Darstellung: Komponenten.
n8n-Workflows
Beide Dateien liegen als JSON-Export in automation/ und werden manuell in n8n importiert (n8n).
„EDV-Kretzer – Status-Hinweis schalten“
automation/n8n-status-schalten.json: Formular-Trigger (Aktion, betroffene Bereiche, freie Bereiche, Text, Dauer) → Knoten „Eingaben aufbereiten“ (Code) → HTTP-Request POST https://api.github.com/repos/pkr-lab/EDV-Kretzer/actions/workflows/status.yml/dispatches mit dem Credential „GitHub PAT (Status-Schalter)“. Es stößt also nur status.yml an. Das Token (fine-grained, nur Repo EDV-Kretzer, Berechtigung Actions Lesen und Schreiben) steht im Token-Register als n8n-github-status-schalter (Rotation siehe Nutzung und Tokens).
„EDV-Kretzer – Update veröffentlichen“ (ohne Wirkung)
automation/n8n-update-veroeffentlichen.json: Webhook POST /publish-update (Header-Auth) oder GitHub-Trigger bei Release → liest data/updates.json über die GitHub-API → hängt einen Eintrag an → schreibt die Datei per PUT zurück. updates.html liest diese Datei nicht mehr (der Verlauf kommt aus releases.json), der Workflow hat daher keinen Effekt auf die Seite und kann in n8n deaktiviert werden.
Debugging und Fehlersuche
Logs: GitHub → Repo EDV-Kretzer → Actions → Lauf auswählen → Schritt aufklappen. Auf dem Server gibt es keine Skriptlogs, das Docroot enthält nur Dateien.
| Symptom | Ursache | Lösung |
|---|---|---|
Deploy schlägt mit missing server host fehl |
Secret NETCUP_HOST fehlt |
Secrets setzen (Installation) |
Deploy: ssh: handshake failed oder Permission denied (publickey) |
Schlüssel nicht in authorized_keys oder falscher Benutzer |
Schlüssel testen, NETCUP_USER prüfen |
Deploy: fatal: not a git repository |
Git-Spiegel ~/git/EDV-Kretzer fehlt oder defekt |
Spiegel neu anlegen (Bare-Repository mit mirror = true) |
| Deploy grün, Seite alt | Browser-Cache oder NETCUP_PATH zeigt auf falsches Docroot |
Strg+F5, Pfad prüfen, Dateizeit auf dem Server |
GitHub-API: HTTP 403 im Release-Verlauf |
Rate-Limit oder fehlendes Token | später erneut, GITHUB_TOKEN im Workflow prüfen |
GitHub-API: HTTP 404 |
Repo umbenannt (REPO im Skript) |
Konstante REPO in build-releases.mjs anpassen |
| Release-Verlauf bleibt leer oder alt | releases.yml ohne Änderung, oder neuer Release hat keine Abschnitte Features und Bug Fixes |
Lauf prüfen; Fallback „Release veröffentlicht.“ ist normal |
releases.yml schlägt bei git push fehl |
Branch-Schutz auf main verhindert Pushes durch die Action |
Ausnahme für github-actions[bot] oder anderen Weg einrichten (TODO: prüfen, ob main geschützt ist) |
| Status-Workflow schlägt im Schritt „status.json schreiben“ fehl | jq meldet einen Fehler zu einer Eingabe (der Schritt gibt den Fehler aus) |
Fehlertext im Lauf lesen, Eingaben prüfen (bis als ISO-8601-Zeitpunkt) |
| Banner erscheint nicht | Workflow nicht gelaufen, until in der Vergangenheit |
Lauf prüfen, data/status.json ansehen |
| n8n-Formular: 403 „Resource not accessible by personal access token“ | Token ohne Berechtigung Actions oder falsches Repo | Token neu erzeugen (Nutzung) |
| n8n-Formular: 401 | Token abgelaufen oder Credential falsch | Credential in n8n erneuern, Register aktualisieren |
| n8n-Formular nicht erreichbar | n8n nur im Heimnetz oder Tailnet erreichbar | VPN, Alternative: Workflow in GitHub starten |
commitlint rot |
Commit-Nachricht im falschen Format | <typ>(<scope>): <beschreibung> |
Weiter: Debugging und Fehlersuche.