PKR-Lab

Konfiguration

Quelle: pkr-lab/pkr-lab-docs/github-workflows/konfiguration.md

Konfiguration

Eingaben von release.yml

Eingabe Standard Bedeutung
branches ["main"] JSON-Liste der Release-Branches ('["main","master"]')
build-script leer Skript im Repo, das Artefakte nach dist/ baut. Es läuft in der Prepare-Phase von semantic-release und bekommt die neue Version als erstes Argument
assets [] JSON-Liste von Glob-Mustern, die ans GitHub-Release angehängt werden ('["dist/*.zip"]')
image leer Name eines Container-Images; gesetzt = nach dem Release docker build aus dem Dockerfile im Repo-Root und Push nach ghcr.io/<owner>/<image>:vX.Y.Z
changelog true CHANGELOG.md pflegen und als Release-Commit auf den Branch pushen; false bei Branches, die nur per Pull Request änderbar sind (seit v1.2.0)
node-version 24 Node.js für npx

Ausgaben: released (true/false) und version (ohne v). released ist nur true, wenn semantic-release in diesem Lauf einen Tag vX.Y.Z erzeugt hat. Der Workflow merkt sich vor dem Lauf alle vorhandenen Tags; ein Re-Run oder ein workflow_dispatch ohne neue Commits meldet deshalb released=false und baut kein Image erneut.

Der Aufrufer muss Rechte vergeben, weil ein wiederverwendbarer Workflow nicht mehr Rechte bekommt als sein Aufrufer: contents: write (Tag, Release, CHANGELOG-Commit), issues: write und pull-requests: write (Kommentare des GitHub-Plugins), packages: write (Image). packages: write ist auch ohne image nötig: GitHub prüft die angeforderten Rechte eines aufgerufenen Workflows beim Start, unabhängig davon, ob der Image-Schritt später läuft. Wer darauf verzichten will, braucht einen eigenen Image-Workflow (Bruch der Schnittstelle, feat!).

Was semantic-release macht

Der Workflow schreibt zur Laufzeit eine .releaserc.json in den Arbeitsbaum mit diesen Plugins. Sie muss dort liegen, weil semantic-release Plugins aus einer Konfiguration außerhalb des Repos relativ zu deren Ordner sucht und die per npx geladenen Plugins dann nicht findet. Vor dem Docker-Build wird die Datei entfernt, damit sie nicht im Build-Kontext landet.

Reihenfolge Plugin Aufgabe
1 commit-analyzer (Preset conventionalcommits) nächste Version aus den Commits seit dem letzten Tag; docs und chore ergeben ein Patch-Release
2 release-notes-generator Release Notes, Abschnitte für feat, fix, perf, revert, docs, chore
3 changelog (nur mit changelog: true) schreibt CHANGELOG.md
4 exec (nur mit build-script) bash '<build-script>' <version>; der Pfad steht in einfachen Anführungszeichen, Leerzeichen und Sonderzeichen sind erlaubt, zusätzliche Argumente im Input nicht
5 git (nur mit changelog: true) committet CHANGELOG.md mit chore(release): X.Y.Z [skip ci]
6 github Tag vX.Y.Z, GitHub-Release, assets

Die npm-Pakete sind exakt gepinnt, Renovate hebt sie über einen Regex-Manager in renovate.json an:

Paket Workflow
semantic-release, @semantic-release/changelog, @semantic-release/git, @semantic-release/exec release.yml
conventional-changelog-conventionalcommits (Hauptversion 8) release.yml
@commitlint/cli commitlint.yml, ci.yml

Der Tag-Aufbau ist vX.Y.Z. Ohne vorhandene Tags beginnt die Zählung bei v1.0.0, sonst beim höchsten Tag der Form vX.Y.Z. Das Preset conventional-changelog-conventionalcommits ist auf Version 8 festgelegt, weil Version 9 einen neueren Changelog-Writer verlangt, als semantic-release mitbringt.

Regeln von commitlint.yml

Regel Wert
Typen feat, fix, docs, chore, refactor, test, ci, build, perf, style, revert
Typ, Scope kleingeschrieben, Typ Pflicht
Beschreibung Pflicht, kein Punkt am Ende
Kopfzeile höchstens 120 Zeichen
Breaking Change ! vor dem Doppelpunkt erlaubt (feat!: …, fix(app)!: …)

Der Workflow bringt einen eigenen Parser für die Kopfzeile mit (parserPreset.parserOpts.headerPattern), der ! kennt. Der Standard-Parser von commitlint (Angular) kennt es nicht und lehnte solche Commits mit type-empty und subject-empty ab.

Geprüft werden alle Commits zwischen Basis und Kopf des Pull Requests; Merge-Commits ignoriert commitlint. Der Job läuft nur bei pull_request und wird bei anderen Ereignissen übersprungen.

hooks/commit-msg prüft lokal dieselben Regeln: Typ, Scope (kleingeschrieben), Doppelpunkt, kein Punkt am Ende und höchstens 120 Zeichen. Merge-, Revert-, fixup- und squash-Zeilen lässt er durch. Der Job commitlint-Regeln in ci.yml schickt dieselben Nachrichten durch Hook und commitlint und schlägt fehl, wenn beide unterschiedlich urteilen.