Hop til hovedindhold

Automatiseret udgivelse

Libre WebUI-releases oprettes fra repositoryets rod med release-scriptet. Scriptet læser den faktiske git-historik siden det forrige versionstag, opdaterer pakkeversioner, skriver changeloggen, kører release-kontroller, committer releasen og opretter versionstagget. GitHub er kilden til build og udgivelse af binærfiler; release-metadata og navngivne artifact-links spejles til projektets Forgejo-repository.

Engangskonfiguration​

Installer afhængigheder, og aktivér repositoryets hooks:

npm install
npm run setup-hooks

Hook-opsætningen konfigurerer:

  • .githooks/commit-msg til validering af Conventional Commits
  • .githooks/pre-commit til formateringskontroller
  • .gitmessage som lokal skabelon til commitbeskeder

Opret en release​

Kør release-scriptet fra et rent worktree på den gren, du vil tagge:

# Patch release
npm run release

# Minor release
npm run release:minor

# Major release
npm run release:major

Scriptet gør automatisk følgende:

  1. Kontrollerer, at arbejdstræet er rent, og at det næste lokale tag er ledigt.
  2. Indsamler evidens fra commits, filer, afhængigheder, sprogfiler og den endnu ikke udgivne changelog.
  3. Genererer release notes ud fra denne evidens.
  4. Opdaterer package.json, pakkefilerne i workspaces, package-lock.json, versionerne for Helm-chart og app samt CHANGELOG.md.
  5. Kører npm run release:check, herunder formatering, lint, builds, tests, sikkerhedsaudit og en dry-run af npm-udgivelsen.
  6. Committer først releasen og opretter det annoterede versionstag, når alle kontroller er bestået.

Changelog​

Forhåndsvis den næste changelog-sektion uden at ændre filer:

npm run changelog

Opdater CHANGELOG.md manuelt fra den genererede sektion:

npm run changelog -- update

Som standard kan changelog-genereringen bede en lokal Ollama-kompatibel model om et poleret udkast og validerer derefter resultatet mod den indsamlede git-evidens. Hvis AI ikke er tilgængelig, eller resultatet ser usikkert ud, falder scriptet tilbage til en deterministisk generator.

Nyttige tilsidesættelser:

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

Push af release​

Når release-commit og annoteret tag er oprettet, udgiver du kun præcis den gren-commit og det tag, som scriptet viser. Produktionsgrenen pushes først til Forgejo og derefter til GitHub, med push af tilhørende tags eksplicit slået fra:

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

Begge returnerede SHA'er for grenen skal være lig med den tilsigtede lokale release-commit. Vent på, at de påkrævede GitHub-workflows for præcis den commit er bestået, før tagget udgives.

Bekræft, at versionstagget ikke allerede findes på nogen af tjenesterne, og push derefter netop det ene tag først til Forgejo og derefter til GitHub:

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^{}'

Erstat vX.Y.Z med release-tagget. For et annoteret tag verificerer du både tagobjektets SHA og SHA'en for den commit, det peger på. Brug aldrig git push --tags, som kan udgive uvedkommende lokale tags.

Release-forløbet i CI​

Et push af et v*-tag kører GitHubs release-workflow. Workflowet:

  • Kører npm run release:check
  • Bygger Electron-artifacts til macOS, Windows og Linux
  • Opretter GitHub-releasen fra den tilsvarende sektion i CHANGELOG.md
  • Spejler release-posten og navngivne artifact-links til Forgejo
  • Bygger Docker-images
  • Udgiver Helm-chartet med samme version som release-tagget
  • Udgiver npm-pakken med NPM_TOKEN

Den samme kontrol kan køres lokalt før tagging:

npm run release:check

Forgejo-spejling​

Spejlingen bruger et personligt Forgejo-adgangstoken, der er gemt som den krypterede GitHub Actions-hemmelighed FORGEJO_TOKEN. Giv kun tokenet scopet write:repository, sørg for, at dets ejer kan skrive til libre-webui/libre-webui, og commit eller udskriv aldrig tokenet.

Spejlingen er bevidst idempotent. Den slår releases op efter tag, opretter kun manglende release-poster, afstemmer deres release-metadata fra GitHub og springer artifact-links over, der allerede findes. Et nyt forsøg efter en netværks- eller workflowfejl fuldfører derfor det manglende arbejde uden at duplikere releases eller assets.

Forgejos release-assets er navngivne eksterne links til den tilsvarende offentlige browser_download_url på GitHub. GitHub forbliver vært for binærfilerne, mens Forgejo viser de samme filnavne til download uden at duplikere titusinder af gigabyte desktop-artifacts. Kildearkiver genereres fortsat uafhængigt fra præcis det samme tag på hver tjeneste.

Forhåndsvis eller udfyld én release​

Se, hvad der ville ændre sig, uden at skrive til Forgejo:

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

Når FORGEJO_TOKEN og GITHUB_TOKEN er indlæst i procesmiljøet fra vedligeholderens secret manager, spejler du releasen:

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

Det præcise tag skal allerede findes på GitHub og Forgejo og pege på samme tagobjekt og samme commit, før en release spejles.

Forhåndsvis eller udfyld alle releases​

Gennemgå hver GitHub Release mod Forgejo:

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

Udfyld hver manglende eller ufuldstændig Forgejo Release:

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

GITHUB_TOKEN er påkrævet til --all, også ved dry-runs, fordi kontrol af præcis tagparitet og søgning efter assets kræver flere forespørgsler, end GitHubs grænse for anonym API-brug tillader. FORGEJO_TOKEN er desuden påkrævet, når --dry-run ikke bruges.

Med --all pagineres begge API'er, og kun GitHub Release-objekter behandles, ikke hvert Git-tag. Et tag, der bevidst ikke har nogen GitHub Release, forbliver et rent tag på Forgejo. Kør dry-run igen efter en udfyldning; den bør ikke rapportere nogen udestående ændringer.

Politik for uforanderlige tags​

Udgivne versionstags er uforanderlige. Når et tag findes på en af de to remotes:

  • Slet det ikke.
  • Force-push det ikke.
  • Flyt det ikke til en rettet commit.
  • Genbrug ikke dets semantiske version til andet indhold.

Hvis indholdet af en udgivet release er forkert, retter du kildekoden og changeloggen og udgiver den næste patchversion. Hvis kun en release-side eller et eksternt asset-link mangler, kører du den idempotente spejling igen uden at røre tagget.

Forgejos v0.8.6-tag blev én gang, med udtrykkelig godkendelse, justeret, da dobbelt release-spejling blev indført. Justeringen reparerede to historiske tagobjekter, der beskrev identiske kildetræer, men fulgte forskellige commit-linjer. Den auditerede migrering er ikke en præcedens for at flytte udgivne tags.

Helm-versionspolicy​

Helm-chartets version, chartets appVersion, rodpakkens version og release-tagget bruger bevidst den samme semantiske version. Release-scriptet hæver dem samlet, og CI afviser uoverensstemmelser.

Chartet udgives kun fra et uforanderligt v*-release-tag. Udgiv ikke ændret chartindhold under en eksisterende chartversion. En ændring af chartet skal gå gennem den næste programrelease, så den får en ny version.

Chartversion 0.14.1 har en engangs-override af digest, fordi den release er ældre end de semantiske Docker-tags. Digesten identificerer det verificerede 0.14.1-image til flere arkitekturer. Release-scriptet rydder denne override, når det opretter den næste release, hvorefter standardimaget følger chartets appVersion.

Docker-workflowet udgiver det semantiske versionstag til GHCR og Docker Hub fra det samme v*-release-tag. Helm-udgivelsen venter op til 20 minutter på det tilsvarende offentlige image på Docker Hub og fejler i stedet for at udgive et chart, hvor standardimaget mangler. Det medfølgende Ollama-image kan konfigureres uafhængigt og bruger som standard sit upstream-tag latest.

Conventional Commits​

Commitbeskeder skal følge Conventional Commit-formatet:

<type>[optional scope]: <description>

Almindelige typer:

  • feat: funktion, som brugerne kan se
  • fix: fejlrettelse
  • docs: opdatering af dokumentation
  • refactor: intern omstrukturering af kode
  • perf: forbedring af ydeevne
  • test: testdækning
  • chore: vedligeholdelse, release- eller buildarbejde

Inkompatible ændringer bruger !:

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

Fejlfinding​

Arbejdsmappen er ikke ren​

Commit eller stash de lokale ændringer før udgivelsen:

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

Ingen ændringer at udgive​

Kontrollér commits siden det forrige tag:

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

Changeloggen skal redigeres manuelt​

Redigér CHANGELOG.md, og commit rettelsen, før tagget udgives:

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

Rul en lokal release-commit tilbage​

Hvis hverken release-commit eller tag er blevet pushet:

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

Hvis en af de to remotes allerede har tagget, må du ikke slette eller erstatte det. Ret problemet på main, opret den næste patchrelease, og udgiv det nye uforanderlige tag gennem hele kontrolforløbet.

Forgejo-spejlingen er ufuldstændig​

Verificer først, at SHA'erne for både tagobjektet og den commit, tagget peger på, matcher på begge remotes. Forhåndsvis og prøv derefter den berørte release igen:

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

En autorisationsfejl betyder, at FORGEJO_TOKEN mangler, er udløbet, ejes af en bruger uden adgang til repositoryet eller mangler write:repository. Et manglende eller afvigende tag på en remote skal undersøges separat; release-spejlingen opretter eller flytter aldrig Git-tags.

Filer for vedligeholdere​

  • .gitmessage: skabelon til commitbeskeder
  • .githooks/commit-msg: validering af Conventional Commits
  • .githooks/pre-commit: formateringskontrol før commit
  • scripts/release.js: orkestrering af releases
  • scripts/mirror-forgejo-releases.mjs: idempotent spejling og udfyldning af Forgejo-releases
  • scripts/generate-changelog.js: kommando til forhåndsvisning og opdatering af changeloggen
  • scripts/lib/releaseNotes.js: indsamling af evidens og generering af changelog
  • .github/workflows/release.yml: tagstyret release-workflow i CI
  • .github/workflows/helm-publish.yml: validering af Helm og udgivelse ved tag

Du kan læse mere om Conventional Commits på https://www.conventionalcommits.org/.