Releaseautomatisering

Libre WebUI-releases worden vanuit de hoofdmap van de repository gemaakt met het releasescript. Het script leest de werkelijke Git-geschiedenis sinds de vorige versietag, werkt pakketversies bij, schrijft de changelog, voert releasecontroles uit, commit de release en maakt de versietag. GitHub is de bron voor builds en de publicatie van binaire bestanden; releasemetadata en benoemde artefactkoppelingen worden gespiegeld naar de Forgejo-repository van het project.

Eenmalige lokale configuratie

Installeer afhankelijkheden en schakel de repositoryhooks in:

npm install
npm run setup-hooks

De hookconfiguratie stelt het volgende in:

• .githooks/commit-msg voor validatie van Conventional Commits
• .githooks/pre-commit voor opmaakcontroles
• .gitmessage als lokale sjabloon voor commitberichten

Een release maken

Voer het releasescript uit vanuit een schone werkstructuur op de branch die u wilt taggen:

# Patch release
npm run release

# Minor release
npm run release:minor

# Major release
npm run release:major

Het script doet automatisch het volgende:

1. Controleert of de werkstructuur schoon is en de volgende lokale tag beschikbaar is.
2. Verzamelt bewijs uit commits, bestanden, afhankelijkheden, locales en niet-uitgebrachte changelogitems.
3. Genereert releaseopmerkingen op basis van dat bewijs.
4. Werkt package.json, workspacepakketbestanden, package-lock.json, de Helm-chart en appversies, en CHANGELOG.md bij.
5. Voert npm run release:check uit, inclusief opmaak, linting, builds, tests, beveiligingscontrole en de droge proefpublicatie van npm.
6. Commit de release en maakt de geannoteerde versietag pas nadat elke controle is geslaagd.

Changelog genereren

Bekijk de volgende changelogsectie zonder bestanden te wijzigen:

npm run changelog

Werk CHANGELOG.md handmatig bij vanuit de gegenereerde sectie:

npm run changelog -- update

Standaard kan de changeloggenerator een lokaal Ollama-compatibel model om een verzorgd concept vragen en controleert hij het resultaat daarna aan de hand van het verzamelde Git-bewijs. Als AI niet beschikbaar is of de uitvoer onveilig lijkt, valt het script terug op een deterministische generator.

Nuttige overrides:

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

Een release pushen

Publiceer na het maken van de releasecommit en geannoteerde tag uitsluitend de exacte branchcommit en tag die het script toont. De productiebranch wordt eerst naar Forgejo en daarna naar GitHub gepusht, waarbij het volgen van tags expliciet is uitgeschakeld:

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 geretourneerde branch-SHA's moeten gelijk zijn aan de bedoelde lokale releasecommit. Wacht totdat de verplichte GitHub-workflows voor precies die commit zijn geslaagd voordat u de tag publiceert.

Controleer dat de versietag nog niet op een van beide diensten bestaat en push vervolgens die ene tag eerst naar Forgejo en daarna naar 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^{}'

Vervang vX.Y.Z door de releasetag. Controleer bij een geannoteerde tag zowel de SHA van het tagobject als de SHA van de uitgepelde commit. Gebruik nooit git push --tags, want daarmee kunt u niet-gerelateerde lokale tags publiceren.

CI-releasepad

Het pushen van een v*-tag start de GitHub-releaseworkflow. De workflow:

• Voert npm run release:check uit
• Bouwt Electron-artefacten voor macOS, Windows en Linux
• Maakt de GitHub-release op basis van de overeenkomende sectie in CHANGELOG.md
• Spiegelt het releaserecord en de benoemde artefactkoppelingen naar Forgejo
• Bouwt Docker-images
• Publiceert de Helm-chart met dezelfde versie als de releasetag
• Publiceert het npm-pakket met NPM_TOKEN

Dezelfde controle kan vóór het taggen lokaal worden uitgevoerd:

npm run release:check

Forgejo-releasespiegel

De spiegel gebruikt een persoonlijk Forgejo-toegangstoken dat als versleuteld GitHub Actions-geheim FORGEJO_TOKEN is opgeslagen. Geef het token uitsluitend het bereik write:repository, zorg dat de eigenaar naar libre-webui/libre-webui kan schrijven en commit of print het token nooit.

De spiegel is bewust idempotent. Hij zoekt releases op tag op, maakt alleen ontbrekende releaserecords aan, brengt hun GitHub-releasemetadata in overeenstemming en slaat artefactkoppelingen over die al bestaan. Als u na een netwerk- of workflowfout opnieuw probeert, wordt het ontbrekende werk daarom voltooid zonder dubbele releases of assets te maken.

Forgejo-releaseassets zijn benoemde externe koppelingen naar de bijbehorende openbare GitHub-browser_download_url. GitHub blijft de host van binaire bestanden, terwijl Forgejo dezelfde downloadbare bestandsnamen toont zonder tientallen gigabytes aan desktopartefacten te dupliceren. Bronarchieven worden op elke dienst onafhankelijk gegenereerd op basis van de exacte tag.

Eén release vooraf bekijken of aanvullen

Bekijk wat er zou veranderen zonder naar Forgejo te schrijven:

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

Laad FORGEJO_TOKEN en GITHUB_TOKEN vanuit de geheime-beheeroplossing van de beheerder in de procesomgeving en spiegel daarna die release:

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

De exacte tag moet al op GitHub en Forgejo bestaan en naar hetzelfde tagobject en dezelfde uitgepelde commit verwijzen voordat een release wordt gespiegeld.

Alle releases vooraf bekijken of aanvullen

Controleer elke GitHub Release ten opzichte van Forgejo:

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

Vul elke ontbrekende of onvolledige Forgejo Release aan:

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

GITHUB_TOKEN is vereist voor --all, ook bij droge proeven, omdat exacte taggelijkheid en het ontdekken van assets meer aanvragen vereisen dan de anonieme API-limiet van GitHub toestaat. FORGEJO_TOKEN is daarnaast vereist wanneer --dry-run niet wordt gebruikt.

Het pad --all bladert door beide API's en kijkt naar GitHub Release-objecten, niet naar elke Git-tag. Een tag die bewust geen GitHub Release heeft, blijft op Forgejo alleen een tag. Voer de droge proef na het aanvullen opnieuw uit; die hoort geen openstaande wijzigingen te melden.

Beleid voor onveranderlijke tags

Gepubliceerde versietags zijn onveranderlijk. Nadat een tag op een van beide remotes bestaat:

• Verwijder hem niet.
• Force-push hem niet.
• Verplaats hem niet naar een gecorrigeerde commit.
• Hergebruik zijn semantische versie niet voor andere inhoud.

Als de inhoud van een gepubliceerde release onjuist is, corrigeert u de bron en changelog en publiceert u de volgende patchversie. Als alleen een releasepagina of externe assetkoppeling ontbreekt, voert u de idempotente spiegel opnieuw uit zonder de tag aan te raken.

De Forgejo-tag v0.8.6 is tijdens de invoering van dubbele releasespiegeling eenmalig en met expliciete goedkeuring opnieuw uitgelijnd. Daarmee werden twee historische tagobjecten hersteld die identieke bronstructuren beschreven maar verschillende commitlijnen volgden. Die gecontroleerde migratie vormt geen precedent voor het verplaatsen van gepubliceerde tags.

Helm-versiebeleid

De version van de Helm-chart, de appVersion van de chart, de versie van het hoofdpakket en de releasetag gebruiken bewust dezelfde semantische versie. Het releasescript verhoogt ze samen en CI wijst een verschil af.

De chart wordt uitsluitend vanuit een onveranderlijke v*-releasetag gepubliceerd. Publiceer geen gewijzigde chartinhoud onder een bestaande chartversie. Een chartwijziging moet via de volgende applicatierelease lopen en krijgt zo een nieuwe versie.

Chartversie 0.14.1 bevat een eenmalige digest-override omdat die release ouder is dan semantische Docker-tags. De digest identificeert de geverifieerde multi-architectuurimage van 0.14.1. Het releasescript wist deze override bij het maken van de volgende release. Daarna verwijst de standaardimage naar de appVersion van de chart.

De Docker-workflow publiceert die semantische-versietag naar GHCR en Docker Hub vanuit dezelfde v*-releasetag. Helm-publicatie wacht maximaal 20 minuten op de overeenkomende openbare Docker Hub-image en faalt in plaats van een chart met een ontbrekende standaardimage te publiceren. De meegeleverde Ollama-image blijft onafhankelijk instelbaar en gebruikt standaard de upstreamtag latest.

Conventional Commits

Commitberichten horen de Conventional Commit-indeling te gebruiken:

<type>[optional scope]: <description>

Veelgebruikte typen:

• feat: functie voor gebruikers
• fix: foutoplossing
• docs: documentatie-update
• refactor: interne herstructurering van code
• perf: prestatieverbetering
• test: testdekking
• chore: onderhoud, release- of bouwwerk

Incompatibele wijzigingen gebruiken !:

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

Problemen oplossen

Werkmap is niet schoon

Commit of stash de lokale wijzigingen voordat u een release maakt:

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

Geen publiceerbare wijzigingen

Controleer de commits sinds de vorige tag:

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

Changelog moet handmatig worden bewerkt

Bewerk CHANGELOG.md en commit de correctie voordat u de tag publiceert:

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

Een lokale releasecommit terugdraaien

Als de releasecommit noch de tag is gepusht:

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

Als de tag al op een van beide remotes bestaat, verwijdert of vervangt u hem niet. Los het probleem op main op, maak de volgende patchrelease en publiceer die nieuwe onveranderlijke tag via de volledige controlepoort.

Forgejo-spiegel is onvolledig

Controleer eerst of de SHA's van het tagobject en de uitgepelde commit op beide remotes overeenkomen. Bekijk en probeer daarna de betrokken release opnieuw:

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

Een autorisatiefout betekent dat FORGEJO_TOKEN ontbreekt, is verlopen, eigendom is van een gebruiker zonder repositorytoegang of het bereik write:repository mist. Een ontbrekende of afwijkende externe tag moet afzonderlijk worden onderzocht; de releasespiegel maakt of verplaatst nooit Git-tags.

Beheerdersbestanden

• .gitmessage - sjabloon voor commitberichten
• .githooks/commit-msg - validatie van Conventional Commits
• .githooks/pre-commit - voorafgaande opmaakcontrole
• scripts/release.js - releaseorkestratie
• scripts/mirror-forgejo-releases.mjs - idempotente Forgejo-releasespiegel en aanvulling
• scripts/generate-changelog.js - opdracht om de changelog vooraf te bekijken/bij te werken
• scripts/lib/releaseNotes.js - bewijsverzameling en changeloggeneratie
• .github/workflows/release.yml - taggestuurde CI-releaseworkflow
• .github/workflows/helm-publish.yml - Helm-validatie en tagpublicatie

Ga voor meer informatie over Conventional Commits naar https://www.conventionalcommits.org/.