Passa al contenuto principale

Automazione delle release

Le release di Libre WebUI vengono create dalla radice del repository mediante lo script di rilascio. Lo script legge la cronologia Git reale a partire dal tag della versione precedente, aggiorna le versioni dei pacchetti, scrive il registro delle modifiche, esegue i controlli di rilascio, crea il commit della release e il relativo tag di versione. GitHub è la fonte per le build e la pubblicazione dei file binari; i metadati della release e i collegamenti denominati agli artefatti vengono replicati nel repository Forgejo del progetto.

Configurazione locale iniziale​

Installa le dipendenze e abilita gli hook del repository:

npm install
npm run setup-hooks

La configurazione degli hook imposta:

  • .githooks/commit-msg per convalidare i Conventional Commit
  • .githooks/pre-commit per i controlli di formattazione
  • .gitmessage come modello locale dei messaggi di commit

Creare una release​

Esegui lo script di rilascio da un albero di lavoro pulito, sul branch a cui vuoi applicare il tag:

# Patch release
npm run release

# Minor release
npm run release:minor

# Major release
npm run release:major

Lo script esegue automaticamente queste operazioni:

  1. Verifica che l'albero di lavoro sia pulito e che il successivo tag locale sia disponibile.
  2. Raccoglie prove relative a commit, file, dipendenze, impostazioni locali e modifiche non ancora pubblicate.
  3. Genera le note di rilascio a partire da tali prove.
  4. Aggiorna package.json, i file dei pacchetti dell'area di lavoro, package-lock.json, le versioni del chart Helm e dell'app e CHANGELOG.md.
  5. Esegue npm run release:check, inclusi formattazione, lint, build, test, controllo di sicurezza e simulazione della pubblicazione npm.
  6. Solo dopo il superamento di tutti i controlli, crea il commit della release e il tag di versione annotato.

Generazione del registro delle modifiche​

Visualizza in anteprima la prossima sezione del registro senza modificare i file:

npm run changelog

Aggiorna manualmente CHANGELOG.md dalla sezione generata:

npm run changelog -- update

Per impostazione predefinita, la generazione del registro può chiedere a un modello locale compatibile con Ollama di produrre una bozza rifinita, quindi convalida il risultato rispetto alle prove Git raccolte. Se l'AI non è disponibile o l'output sembra non sicuro, lo script ripiega su un generatore deterministico.

Override utili:

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

Eseguire il push di una release​

Dopo aver creato il commit della release e il tag annotato, pubblica esclusivamente il commit del branch e il tag esatti indicati dallo script. Il branch di produzione viene inviato prima a Forgejo e poi a GitHub, disabilitando esplicitamente i tag seguiti:

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

Entrambi gli SHA del branch restituiti devono corrispondere al commit locale previsto per la release. Prima di pubblicare il tag, attendi che i workflow GitHub obbligatori per quel preciso commit vengano completati correttamente.

Verifica che il tag di versione non esista già su nessuno dei due servizi, quindi invia quel singolo tag prima a Forgejo e poi a 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^{}'

Sostituisci vX.Y.Z con il tag della release. Per un tag annotato, verifica sia lo SHA dell'oggetto tag sia lo SHA del commit a cui viene risolto. Non usare mai git push --tags, perché può pubblicare tag locali non correlati.

Percorso di rilascio CI​

Il push di un tag v* avvia il workflow di rilascio GitHub. Il workflow:

  • Esegue npm run release:check
  • Crea gli artefatti Electron per macOS, Windows e Linux
  • Crea la release GitHub dalla sezione corrispondente di CHANGELOG.md
  • Replica il record della release e i collegamenti denominati agli artefatti in Forgejo
  • Crea le immagini Docker
  • Pubblica il chart Helm con la stessa versione del tag di release
  • Pubblica il pacchetto npm con NPM_TOKEN

Lo stesso controllo può essere eseguito localmente prima di creare il tag:

npm run release:check

Mirror delle release su Forgejo​

Il mirror usa un token di accesso personale Forgejo archiviato come secret crittografato di GitHub Actions FORGEJO_TOKEN. Assegna al token esclusivamente l'ambito write:repository, assicurati che il proprietario possa scrivere in libre-webui/libre-webui e non eseguire mai il commit o la stampa del token.

Il mirror è intenzionalmente idempotente. Cerca le release per tag, crea solo i record mancanti, riconcilia i relativi metadati con la release GitHub e ignora i collegamenti agli artefatti già esistenti. Una ripetizione dopo un errore di rete o del workflow completa quindi il lavoro mancante senza duplicare release o risorse.

Gli asset delle release Forgejo sono collegamenti esterni denominati che puntano ai corrispondenti browser_download_url pubblici di GitHub. GitHub rimane l'host dei file binari, mentre Forgejo mostra gli stessi nomi di file scaricabili senza duplicare decine di gigabyte di artefatti desktop. Gli archivi dei sorgenti restano generati indipendentemente dal tag esatto su ciascun servizio.

Anteprima o recupero di una release​

Esamina ciò che cambierebbe senza scrivere su Forgejo:

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

Dopo aver caricato FORGEJO_TOKEN e GITHUB_TOKEN nell'ambiente del processo dal gestore di segreti del manutentore, replica la release:

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

Il tag esatto deve già esistere su GitHub e Forgejo e risolversi nello stesso oggetto tag e nello stesso commit prima di poter replicare una release.

Anteprima o recupero di tutte le release​

Controlla ogni release GitHub rispetto a Forgejo:

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

Completa ogni release Forgejo mancante o incompleta:

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

GITHUB_TOKEN è necessario per --all, comprese le simulazioni, perché la verifica esatta della parità dei tag e l'individuazione degli asset richiedono più richieste di quante ne consenta il limite anonimo dell'API GitHub. FORGEJO_TOKEN è inoltre necessario ogni volta che non si usa --dry-run.

Il percorso --all pagina entrambe le API e considera gli oggetti Release di GitHub, non tutti i tag Git. Un tag che intenzionalmente non ha una release GitHub rimane soltanto un tag su Forgejo. Esegui nuovamente la simulazione dopo il recupero: non dovrebbe segnalare modifiche in sospeso.

Criterio di immutabilità dei tag​

I tag di versione pubblicati sono immutabili. Quando un tag esiste su uno dei due servizi remoti:

  • Non eliminarlo.
  • Non eseguire un push forzato.
  • Non spostarlo su un commit corretto.
  • Non riutilizzare la sua versione semantica per contenuti diversi.

Se i contenuti di una release pubblicata sono errati, correggi il sorgente e il registro delle modifiche e pubblica la versione patch successiva. Se manca solo una pagina di release o un collegamento esterno a un asset, riesegui il mirror idempotente senza modificare il tag.

Il tag Forgejo v0.8.6 è stato riallineato una sola volta, previa approvazione esplicita, durante l'introduzione del doppio mirroring delle release. L'operazione ha corretto due oggetti tag storici che descrivevano alberi dei sorgenti identici ma seguivano sequenze di commit diverse. Quella migrazione sottoposta a controllo non costituisce un precedente per lo spostamento di tag pubblicati.

Criterio delle versioni Helm​

La version del chart Helm, il suo appVersion, la versione del pacchetto radice e il tag di release usano intenzionalmente la stessa versione semantica. Lo script di rilascio li aggiorna insieme e la CI rifiuta eventuali discrepanze.

Il chart viene pubblicato solo da un tag di release v* immutabile. Non pubblicare contenuti del chart modificati con una versione del chart esistente. Una modifica al chart deve passare per la successiva release dell'applicazione, così riceve una nuova versione.

La versione 0.14.1 del chart include un override del digest utilizzato una sola volta, perché quella release precede i tag Docker semantici. Il digest identifica l'immagine multiarchitettura 0.14.1 verificata. Lo script di rilascio rimuove questo override quando crea la release successiva, dopodiché l'immagine predefinita viene risolta tramite appVersion del chart.

Il workflow Docker pubblica quel tag di versione semantica su GHCR e Docker Hub a partire dallo stesso tag di release v*. La pubblicazione Helm attende fino a 20 minuti l'immagine Docker Hub pubblica corrispondente e non riesce, invece di pubblicare un chart con un'immagine predefinita mancante. L'immagine Ollama inclusa rimane configurabile in modo indipendente e usa per impostazione predefinita il tag upstream latest.

Conventional Commit​

I messaggi di commit devono seguire il formato Conventional Commit:

<type>[optional scope]: <description>

Tipi comuni:

  • feat: funzionalità rivolta agli utenti
  • fix: correzione di un bug
  • docs: aggiornamento della documentazione
  • refactor: ristrutturazione interna del codice
  • perf: miglioramento delle prestazioni
  • test: copertura dei test
  • chore: manutenzione, release o attività di build

Le modifiche incompatibili usano !:

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

Risoluzione dei problemi​

La directory di lavoro non è pulita​

Esegui il commit o metti da parte le modifiche locali prima di creare una release:

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

Nessuna modifica pubblicabile​

Controlla i commit successivi al tag precedente:

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

Il registro delle modifiche richiede una modifica manuale​

Modifica CHANGELOG.md, quindi esegui il commit della correzione prima di pubblicare il tag:

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

Annullare un commit di release locale​

Se né il commit della release né il tag sono stati inviati:

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

Se il tag è già presente su uno dei servizi remoti, non eliminarlo né sostituirlo. Correggi il problema su main, crea la release patch successiva e pubblica il nuovo tag immutabile attraverso l'intero processo di verifica.

Il mirror Forgejo è incompleto​

Verifica innanzitutto che l'oggetto tag remoto e gli SHA del commit a cui viene risolto corrispondano. Quindi visualizza in anteprima e riprova la release interessata:

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

Un errore di autorizzazione indica che FORGEJO_TOKEN è mancante, scaduto, appartiene a un utente privo di accesso al repository oppure non dispone di write:repository. Un tag remoto mancante o diverso deve essere esaminato separatamente; il mirror delle release non crea né sposta mai i tag Git.

File per i manutentori​

  • .gitmessage - modello dei messaggi di commit
  • .githooks/commit-msg - convalida dei Conventional Commit
  • .githooks/pre-commit - verifica preliminare della formattazione
  • scripts/release.js - orchestrazione delle release
  • scripts/mirror-forgejo-releases.mjs - mirror e recupero idempotente delle release Forgejo
  • scripts/generate-changelog.js - comando di anteprima/aggiornamento del registro delle modifiche
  • scripts/lib/releaseNotes.js - raccolta delle prove e generazione del registro delle modifiche
  • .github/workflows/release.yml - workflow CI di rilascio avviato dal tag
  • .github/workflows/helm-publish.yml - convalida Helm e pubblicazione del tag

Per ulteriori informazioni sui Conventional Commit, visita https://www.conventionalcommits.org/.