Aller au contenu principal

Automatisation des versions

Les versions de Libre WebUI sont créées depuis la racine du dépôt à l'aide du script de publication. Celui-ci lit l'historique Git réel depuis la balise de version précédente, met à jour les versions des paquets, rédige le journal des modifications, exécute les contrôles de publication, valide la version et crée sa balise. GitHub constitue la source de compilation et de publication des binaires ; les métadonnées de version et les liens nommés vers les artefacts sont répliqués dans le dépôt Forgejo du projet.

Configuration locale initiale​

Installez les dépendances et activez les hooks du dépôt :

npm install
npm run setup-hooks

La configuration des hooks définit :

  • .githooks/commit-msg pour valider les commits conventionnels
  • .githooks/pre-commit pour les contrôles de mise en forme
  • .gitmessage comme modèle local de message de commit

Créer une version​

Exécutez le script de publication depuis un arbre de travail propre sur la branche à baliser :

# Patch release
npm run release

# Minor release
npm run release:minor

# Major release
npm run release:major

Le script effectue automatiquement les opérations suivantes :

  1. Il vérifie que l'arbre de travail est propre et que la prochaine balise locale est disponible.
  2. Il rassemble les preuves provenant des commits, fichiers, dépendances, langues et éléments non publiés du journal des modifications.
  3. Il génère les notes de version à partir de ces preuves.
  4. Il met à jour package.json, les fichiers de paquets de l'espace de travail, package-lock.json, les versions du chart Helm et de l'application, ainsi que CHANGELOG.md.
  5. Il exécute npm run release:check, notamment la mise en forme, le lint, les compilations, les tests, l'audit de sécurité et la simulation de publication npm.
  6. Ce n'est qu'une fois tous les contrôles réussis qu'il valide la version et crée la balise de version annotée.

Génération du journal des modifications​

Prévisualisez la prochaine section du journal sans modifier les fichiers :

npm run changelog

Mettez à jour CHANGELOG.md manuellement à partir de la section générée :

npm run changelog -- update

Par défaut, le générateur du journal peut demander à un modèle local compatible avec Ollama de produire un brouillon soigné, puis valide le résultat par rapport aux preuves Git rassemblées. Si l'IA est indisponible ou que sa sortie paraît dangereuse, le script revient à un générateur déterministe.

Substitutions utiles :

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

Pousser une version​

Une fois le commit de publication et la balise annotée créés, ne publiez que le commit de branche et la balise exacts indiqués par le script. La branche de production est d'abord poussée vers Forgejo, puis vers GitHub, en désactivant explicitement les balises suivies :

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

Les SHA de branche renvoyés doivent tous deux être identiques au commit de publication local prévu. Attendez que les workflows GitHub requis pour ce commit précis réussissent avant de publier la balise.

Vérifiez que la balise de version n'existe encore sur aucun des deux services, puis poussez cette seule balise, d'abord vers Forgejo et ensuite vers 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^{}'

Remplacez vX.Y.Z par la balise de version. Pour une balise annotée, vérifiez à la fois le SHA de l'objet balise et le SHA du commit déréférencé. N'utilisez jamais git push --tags, car cette commande peut publier des balises locales sans rapport.

Parcours de publication dans la CI​

Pousser une balise v* lance le workflow de publication GitHub. Celui-ci :

  • Exécute npm run release:check
  • Compile les artefacts Electron pour macOS, Windows et Linux
  • Crée la version GitHub à partir de la section correspondante de CHANGELOG.md
  • Réplique la fiche de version et les liens nommés vers les artefacts dans Forgejo
  • Construit les images Docker
  • Publie le chart Helm avec la même version que la balise de publication
  • Publie le paquet npm avec NPM_TOKEN

Le même contrôle peut être exécuté localement avant le balisage :

npm run release:check

Miroir des versions Forgejo​

Le miroir utilise un jeton d'accès personnel Forgejo stocké dans le secret chiffré GitHub Actions FORGEJO_TOKEN. N'accordez au jeton que la portée write:repository, assurez-vous que son propriétaire peut écrire dans libre-webui/libre-webui et ne validez ni n'affichez jamais le jeton.

Le miroir est délibérément idempotent. Il recherche les versions par balise, ne crée que les fiches de version manquantes, harmonise leurs métadonnées avec celles de la version GitHub et ignore les liens vers les artefacts qui existent déjà. Une nouvelle tentative après une défaillance du réseau ou du workflow termine donc le travail manquant sans dupliquer les versions ni les ressources.

Les ressources des versions Forgejo sont des liens externes nommés pointant vers le browser_download_url public correspondant sur GitHub. GitHub reste l'hôte des binaires, tandis que Forgejo affiche les mêmes noms de fichiers téléchargeables sans dupliquer des dizaines de gigaoctets d'artefacts d'applications de bureau. Les archives des sources restent générées séparément à partir de la balise exacte sur chaque service.

Prévisualiser ou compléter une version​

Inspectez ce qui changerait sans écrire dans Forgejo :

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

Après avoir chargé FORGEJO_TOKEN et GITHUB_TOKEN dans l'environnement du processus depuis le gestionnaire de secrets de la personne responsable, répliquez cette version :

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

La balise exacte doit déjà exister sur GitHub et Forgejo et correspondre au même objet balise et au même commit déréférencé avant qu'une version ne soit mise en miroir.

Prévisualiser ou compléter toutes les versions​

Comparez chaque version GitHub à Forgejo :

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

Complétez chaque version Forgejo manquante ou incomplète :

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

GITHUB_TOKEN est requis pour --all, y compris lors des simulations, car la vérification exacte de la parité des balises et la découverte des ressources nécessitent davantage de requêtes que ne le permet la limite de l'API anonyme de GitHub. FORGEJO_TOKEN est également requis lorsque --dry-run n'est pas utilisé.

Le parcours --all pagine les deux API et tient compte des objets de version GitHub, pas de toutes les balises Git. Une balise qui ne possède volontairement aucune version GitHub reste uniquement une balise sur Forgejo. Relancez la simulation après avoir complété les versions : elle ne doit signaler aucune modification en attente.

Politique d'immuabilité des balises​

Les balises de version publiées sont immuables. Dès qu'une balise existe sur l'un des dépôts distants :

  • Ne la supprimez pas.
  • Ne la poussez pas de force.
  • Ne la déplacez pas vers un commit corrigé.
  • Ne réutilisez pas sa version sémantique pour un contenu différent.

Si le contenu d'une version publiée est incorrect, corrigez les sources et le journal des modifications, puis publiez la version corrective suivante. Si seule une page de version ou un lien externe vers une ressource manque, relancez le miroir idempotent sans toucher à la balise.

La balise Forgejo v0.8.6 a fait l'objet d'un réalignement exceptionnel et explicitement approuvé lors de l'introduction de la double mise en miroir des versions. Il a corrigé deux objets balises historiques qui décrivaient des arbres de sources identiques, mais suivaient des lignées de commits différentes. Cette migration auditée ne constitue pas un précédent permettant de déplacer des balises publiées.

Politique de versions Helm​

La version du chart Helm, son appVersion, la version du paquet racine et la balise de publication utilisent volontairement la même version sémantique. Le script de publication les fait progresser ensemble et la CI rejette toute divergence.

Le chart n'est publié qu'à partir d'une balise de version v* immuable. Ne publiez pas un contenu de chart modifié sous une version existante. Toute modification du chart doit passer par la prochaine version de l'application afin de recevoir une nouvelle version.

La version 0.14.1 du chart comporte une substitution exceptionnelle de condensat, car cette version est antérieure aux balises Docker sémantiques. Le condensat identifie l'image multiarchitecture 0.14.1 vérifiée. Le script de publication efface cette substitution lorsqu'il crée la version suivante ; l'image par défaut est ensuite résolue à partir de l'appVersion du chart.

Le workflow Docker publie cette balise de version sémantique sur GHCR et Docker Hub depuis la même balise de publication v*. La publication Helm attend jusqu'à 20 minutes l'image Docker Hub publique correspondante et échoue au lieu de publier un chart dont l'image par défaut est manquante. L'image Ollama incluse reste configurable indépendamment et utilise par défaut sa balise amont latest.

Commits conventionnels​

Les messages de commit doivent respecter le format Conventional Commit :

<type>[optional scope]: <description>

Types courants :

  • feat : fonctionnalité visible par les utilisateurs
  • fix : correction de bogue
  • docs : mise à jour de la documentation
  • refactor : restructuration interne du code
  • perf : amélioration des performances
  • test : couverture des tests
  • chore : maintenance, publication ou travail de compilation

Les changements incompatibles utilisent ! :

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

Dépannage​

Le répertoire de travail n'est pas propre​

Validez ou remisez les modifications locales avant de publier :

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

Aucun changement publiable​

Examinez les commits depuis la balise précédente :

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

Le journal des modifications nécessite une intervention manuelle​

Modifiez CHANGELOG.md, puis validez la correction avant de publier la balise :

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

Annuler un commit de publication local​

Si ni le commit ni la balise de publication n'ont été poussés :

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

Si l'un des dépôts distants possède déjà la balise, ne la supprimez ni ne la remplacez. Corrigez le problème sur main, créez la version corrective suivante et publiez cette nouvelle balise immuable en passant par l'intégralité des contrôles.

Le miroir Forgejo est incomplet​

Vérifiez d'abord que les SHA de l'objet balise et du commit déréférencé correspondent sur les deux dépôts distants. Ensuite, prévisualisez la version concernée et relancez-la :

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

Un échec d'autorisation signifie que FORGEJO_TOKEN est absent, expiré, appartient à un utilisateur sans accès au dépôt ou ne possède pas la portée write:repository. Une balise distante absente ou différente doit faire l'objet d'une enquête distincte ; le miroir de versions ne crée ni ne déplace jamais de balises Git.

Fichiers destinés à la maintenance​

  • .gitmessage - modèle de message de commit
  • .githooks/commit-msg - validation des commits conventionnels
  • .githooks/pre-commit - contrôle préliminaire de la mise en forme
  • scripts/release.js - orchestration des publications
  • scripts/mirror-forgejo-releases.mjs - miroir idempotent des versions Forgejo et complément des versions antérieures
  • scripts/generate-changelog.js - commande de prévisualisation et de mise à jour du journal des modifications
  • scripts/lib/releaseNotes.js - collecte des preuves et génération du journal des modifications
  • .github/workflows/release.yml - workflow de publication CI déclenché par les balises
  • .github/workflows/helm-publish.yml - validation Helm et publication des balises

Pour en savoir plus sur Conventional Commits, consultez https://www.conventionalcommits.org/.