Zum Hauptinhalt springen

Release-Automatisierung

Releases entstehen im Repository-Stamm mit dem Release-Skript. Es liest die Git-Historie seit dem letzten Tag, aktualisiert Paketversionen und Changelog, führt Prüfungen aus, erstellt den Commit und den Tag. GitHub baut und hostet Binärdateien; Metadaten und benannte Artefaktlinks werden nach Forgejo gespiegelt.

Einmalige lokale Einrichtung​

npm install
npm run setup-hooks

Die Einrichtung konfiguriert .githooks/commit-msg für Conventional Commits, .githooks/pre-commit für Formatierung und .gitmessage als Vorlage.

Release erstellen​

Führe das Skript in einem sauberen Worktree auf dem zu taggenden Branch aus:

# Patch release
npm run release

# Minor release
npm run release:minor

# Major release
npm run release:major

Es prüft Worktree und Tag, sammelt Commit-, Datei-, Abhängigkeits-, Locale- und Changelog-Evidenz, erzeugt Notizen, aktualisiert package.json, Workspace-Pakete, package-lock.json, Helm-Versionen und CHANGELOG.md, führt npm run release:check einschließlich Format, Lint, Builds, Tests, Audit und npm-Dry-run aus und erstellt erst nach vollständigem Erfolg Commit und annotierten Tag.

Changelog-Erzeugung​

Vorschau ohne Änderungen:

npm run changelog

Manuell aktualisieren:

npm run changelog -- update

Standardmäßig kann ein lokales Ollama-kompatibles Modell einen Entwurf erstellen, der gegen Git-Evidenz geprüft wird. Bei Ausfall oder unsicherer Ausgabe greift ein deterministischer Generator.

CHANGELOG_AI=0 npm run release:minor
CHANGELOG_AI_MODEL=glm-5.2:cloud npm run changelog
OLLAMA_BASE_URL=http://127.0.0.1:11434 npm run release

Release pushen​

Pushe ausschließlich den angezeigten Branch-Commit und Tag. Zuerst Forgejo, dann GitHub, ohne Follow-Tags:

git -c push.followTags=false push \
  https://git.kroonen.ai/libre-webui/libre-webui.git \
  HEAD:refs/heads/main
git ls-remote \
  https://git.kroonen.ai/libre-webui/libre-webui.git \
  refs/heads/main

git -c push.followTags=false push \
  https://github.com/libre-webui/libre-webui.git \
  HEAD:refs/heads/main
git ls-remote \
  https://github.com/libre-webui/libre-webui.git \
  refs/heads/main

Beide SHAs müssen dem lokalen Release-Commit entsprechen. Warte auf die erforderlichen GitHub-Workflows. Prüfe danach, dass der Tag nirgends existiert, und pushe genau ihn:

git ls-remote \
  https://git.kroonen.ai/libre-webui/libre-webui.git \
  'refs/tags/vX.Y.Z' 'refs/tags/vX.Y.Z^{}'
git ls-remote \
  https://github.com/libre-webui/libre-webui.git \
  'refs/tags/vX.Y.Z' 'refs/tags/vX.Y.Z^{}'

git -c push.followTags=false push \
  https://git.kroonen.ai/libre-webui/libre-webui.git \
  refs/tags/vX.Y.Z:refs/tags/vX.Y.Z
git -c push.followTags=false push \
  https://github.com/libre-webui/libre-webui.git \
  refs/tags/vX.Y.Z:refs/tags/vX.Y.Z

git ls-remote \
  https://git.kroonen.ai/libre-webui/libre-webui.git \
  'refs/tags/vX.Y.Z' 'refs/tags/vX.Y.Z^{}'
git ls-remote \
  https://github.com/libre-webui/libre-webui.git \
  'refs/tags/vX.Y.Z' 'refs/tags/vX.Y.Z^{}'

Ersetze vX.Y.Z. Prüfe Tagobjekt und aufgelösten Commit. Verwende nie git push --tags.

CI-Release-Pfad​

Ein v*-Tag startet: npm run release:check, Electron-Builds für macOS/Windows/Linux, GitHub-Release aus CHANGELOG.md, Forgejo-Spiegelung, Docker-Images, Helm-Chart mit derselben Version und npm-Veröffentlichung mit NPM_TOKEN.

npm run release:check

Forgejo-Release-Spiegel​

Der Spiegel nutzt das verschlüsselte Actions-Secret FORGEJO_TOKEN. Gewähre nur write:repository, stelle Schreibzugriff auf libre-webui/libre-webui sicher und gib den Token nie aus. Der Ablauf ist idempotent: Er erstellt nur fehlende Releases, gleicht GitHub-Metadaten ab und überspringt vorhandene Links.

Forgejo-Assets sind benannte externe Links zum öffentlichen GitHub-browser_download_url; Binärdateien werden nicht dupliziert. Quellarchive entstehen auf beiden Diensten unabhängig aus dem exakten Tag.

Ein Release anzeigen oder nachtragen​

node scripts/mirror-forgejo-releases.mjs --tag vX.Y.Z --dry-run

Lade FORGEJO_TOKEN und GITHUB_TOKEN aus dem Secret-Manager und spiegele:

node scripts/mirror-forgejo-releases.mjs --tag vX.Y.Z

Der exakte Tag muss auf beiden Diensten dasselbe Tagobjekt und denselben Commit ergeben.

Alle Releases anzeigen oder nachtragen​

node scripts/mirror-forgejo-releases.mjs --all --dry-run
node scripts/mirror-forgejo-releases.mjs --all

GITHUB_TOKEN ist für --all auch beim Dry-run nötig; FORGEJO_TOKEN zusätzlich ohne --dry-run. Der Pfad paginiert Release-Objekte, nicht alle Git-Tags. Tags ohne GitHub-Release bleiben Tags. Ein anschließender Dry-run sollte nichts melden.

Richtlinie für unveränderliche Tags​

Veröffentlichte Tags werden nie gelöscht, force-gepusht, auf einen anderen Commit verschoben oder für andere Inhalte wiederverwendet. Fehler werden im nächsten Patch korrigiert; fehlende Release-Seiten oder Links durch erneute Spiegelung.

Der Forgejo-Tag v0.8.6 wurde bei Einführung der Doppelspiegelung einmalig genehmigt neu ausgerichtet, um identische Quellbäume mit unterschiedlichen Historien zu korrigieren. Dies ist kein Präzedenzfall.

Helm-Versionsrichtlinie​

Chart-version, appVersion, Root-Paket und Tag verwenden dieselbe semantische Version; CI lehnt Abweichungen ab. Charts werden nur aus unveränderlichen v*-Tags veröffentlicht. Änderungen benötigen eine neue Anwendungsversion.

Chart 0.14.1 besitzt einmalig ein Digest-Override, da es semantischen Docker-Tags vorausgeht. Der Digest identifiziert das geprüfte Multiarch-Image. Das nächste Release entfernt ihn; danach folgt das Standardimage appVersion.

Docker publiziert denselben Tag auf GHCR und Docker Hub. Helm wartet bis zu 20 Minuten auf das öffentliche Image und scheitert andernfalls. Das enthaltene Ollama bleibt separat konfigurierbar und nutzt standardmäßig latest.

Conventional Commits​

<type>[optional scope]: <description>
  • feat: Benutzerfunktion
  • fix: Fehlerkorrektur
  • docs: Dokumentation
  • refactor: interne Umstrukturierung
  • perf: Leistung
  • test: Tests
  • chore: Wartung, Release oder Build

Breaking Changes verwenden !:

git commit -m "feat!: remove deprecated endpoint"
git commit -m "fix(auth)!: change token validation"

Fehlerbehebung​

Arbeitsverzeichnis ist nicht sauber​

git status --short
git add .
git commit -m "fix: resolve pending changes"

Keine veröffentlichbaren Änderungen​

git log $(git describe --tags --abbrev=0)..HEAD --oneline

Changelog muss manuell bearbeitet werden​

git add CHANGELOG.md
git commit -m "docs: refine changelog"

Lokalen Release-Commit zurücknehmen​

Nur wenn nichts gepusht wurde:

git tag -d v0.12.0
git reset --soft HEAD~1

Existiert der Tag remote, korrigiere main und veröffentliche den nächsten Patch über die vollständige Prüfung.

Forgejo-Spiegel ist unvollständig​

node scripts/mirror-forgejo-releases.mjs --tag vX.Y.Z --dry-run
node scripts/mirror-forgejo-releases.mjs --tag vX.Y.Z

Autorisierungsfehler bedeuten fehlenden, abgelaufenen, unberechtigten oder nicht mit write:repository versehenen FORGEJO_TOKEN. Fehlende oder abweichende Tags müssen separat untersucht werden; der Spiegel erstellt oder verschiebt sie nie.

Maintainer-Dateien​

  • .gitmessage - Commit-Vorlage
  • .githooks/commit-msg - Conventional-Commit-Prüfung
  • .githooks/pre-commit - Formatprüfung
  • scripts/release.js - Orchestrierung
  • scripts/mirror-forgejo-releases.mjs - idempotenter Spiegel und Backfill
  • scripts/generate-changelog.js - Changelog-Vorschau/-Update
  • scripts/lib/releaseNotes.js - Evidenz und Changelog
  • .github/workflows/release.yml - taggesteuertes Release
  • .github/workflows/helm-publish.yml - Helm-Validierung/-Veröffentlichung

Mehr zu Conventional Commits: https://www.conventionalcommits.org/.