Aller au contenu

Créer un tag de release

Vous êtes mainteneur·se de Kirexo et vous voulez déclencher une release : créer un tag Git de version sémantique (MAJEUR.MINEUR.CORRECTIF, ex. 0.0.1) qui enchaîne automatiquement le build des images Docker, le déploiement de la documentation sur GitLab Pages et la création de la release GitLab avec changelog.

Le workflow recommandé met à jour le CHANGELOG.md dans le même mouvement, via le skill /creer-tag. Cette recette présente d'abord ce workflow, puis les trois façons de déclencher la pose du tag à plus bas niveau (Méthodes A, B, C) — utiles si vous voulez taguer sans toucher au changelog.

Choisir le niveau d'incrément

Avec le skill /creer-tag, le niveau est déterminé par Claude à partir des commits depuis le dernier tag semver, sauf si vous le passez en argument : votre choix prime toujours (cf. Invocation). Dans les deux cas, la règle est la même. Tant que Kirexo est en 0.y.z (avant 1.0.0) :

Niveau Quand l'utiliser Exemple depuis 0.0.3
patch Corrections et évolutions compatibles pour un installateur 0.0.4
minor Rupture pour un installateur : variable d'environnement renommée ou supprimée, étape manuelle de mise à jour, migration non réversible. La note de version doit le signaler. 0.1.0
major Réservé au passage à 1.0.0 1.0.0

En 0.y.z, une mineure peut donc casser : c'est la convention semver avant 1.0.0, que les installateurs lisent via les notes de version.

S'il n'existe encore aucune version semver, la version produite est 0.0.1 quel que soit le niveau retenu.

Pour connaître la version qui sera produite sans rien modifier, utilisez castor tag:next-version :

castor tag:next-version --bump=minor

La cible lit les tags Git locaux (faites git fetch --tags avant si besoin) et affiche la version seule, sur une ligne.

Workflow recommandé : le skill /creer-tag

Le skill /creer-tag est l'enrobage de référence autour de la Méthode C. Il garantit que le commit taggé contient déjà sa propre section de CHANGELOG.md : la version est calculée d'avance et imposée au job CI (TAG_NAME), au lieu d'être calculée côté serveur au moment de la pose. La section de changelog peut donc être écrite avant la pose du tag.

Invocation : /creer-tag, /creer-tag patch, /creer-tag minor ou /creer-tag major.

  • Sans argument, Claude détermine le niveau à partir des commits depuis le dernier tag semver (git log --no-merges <dernier-tag>..origin/main), selon la règle ci-dessus. Il annonce son choix avec une justification d'une ligne, puis lance prepare.sh sans attendre de réponse. Pour la première release (aucun tag semver), il prend patch : la version est 0.0.1 quel que soit le niveau.
  • Avec un argument, le niveau passé est utilisé tel quel.

Le skill met aussi à jour le site vitrine (site/) dans la même release. Le déroulé tient en trois temps : deux temps locaux sans effet, puis un temps qui pousse :

prepare.sh <niveau>                    →  branche release-<version> + CHANGELOG.md + site/data/release.json   (LOCAL)
castor site:context --bump=<niveau>    →  contexte compact ; rédaction de la partie variable de site/          (LOCAL)
release.sh <version> <niveau>          →  site-diff-check → commit CHANGELOG.md + site/ → MR → tag:create      (REMOTE, lancé par vous)

Le changelog et la partie fixe du site (version, date, statuts) sont générés sans LLM. La seule partie rédigée par Claude est le texte du site, bornée par le budget du niveau (cf. étape 3).

1. Préparer (local)

Le script se lance depuis n'importe quelle branche, worktree compris, à deux conditions : HEAD est exactement le commit de origin/main, et l'arbre de travail est propre. Par exemple pour une patch :

bash .claude/skills/creer-tag/bin/prepare.sh patch

L'argument vaut patch (défaut), minor ou major. Le script :

  1. vérifie que l'arbre de travail est propre (modifications indexées ou non ; les fichiers non suivis sont tolérés) ;
  2. rafraîchit origin/main et les tags (git fetch --tags) ;
  3. vérifie que HEAD est le commit de origin/main. Le nom de la branche courante n'entre pas en compte, seul le commit compte : le changelog est généré depuis exactement ce qui partira en release. Sinon, le script s'arrête avec ✗ HEAD (<sha court>) n'est pas le commit de origin/main — synchronise d'abord. ;
  4. vérifie qu'au moins un commit existe depuis la release précédente (plus haute version semver ; pour la toute première release seulement, dernier ancien tag horodaté) ;
  5. calcule la version avec castor tag:next-version --bump=<niveau> ;
  6. crée la branche release-<version> à partir de HEAD et bascule dessus ;
  7. lance castor changelog:prepare --name <version>, qui insère la section générée en tête de CHANGELOG.md ;
  8. lance castor site:refresh --name=<version>, qui valide site/data/statuts.json puis écrit site/data/release.json (version et date du jour).

La section est affichée, suivie de trois lignes, par exemple pour une minor :

Branche : release-0.2.0
Site    : castor site:context --bump=minor
Ship    : bash .claude/skills/creer-tag/bin/release.sh 0.2.0 minor
TAG_NAME=0.2.0

La dernière ligne de sortie est toujours TAG_NAME=<version>. Notez cette version.

Si site/data/statuts.json est invalide, site:refresh échoue et le script s'arrête avant la ligne TAG_NAME=. Corrigez le fichier sur main, puis repartez de zéro : git checkout -- CHANGELOG.md site/data/release.json, git switch <branche de départ> (celle sur laquelle vous avez lancé prepare.sh), git branch -D release-<version>.

La génération du changelog est déterministe : les commits depuis la version précédente sont classés par rubrique selon leur préfixe Conventional Commits (cf. Convention du CHANGELOG.md). Aucune rédaction par un LLM.

Si le script échoue (HEAD différent de origin/main, arbre sale, aucun commit nouveau, branche release-<version> déjà présente), relancer recalcule la même version tant qu'aucun tag n'a été posé : supprimez d'abord la branche locale release-<version>.

2. Relire (optionnel)

La section est déjà affichée par prepare.sh. Pour ajuster un libellé, éditez CHANGELOG.md à la main avant l'étape suivante — la génération est volontairement brute (sujets de commits nettoyés, classés). Pour une minor, c'est ici que vous décrivez la rupture et la marche à suivre pour l'installateur.

3. Mettre à jour le site

Le skill lance d'abord :

castor site:context --bump=minor

La cible imprime, en lecture seule, tout ce qu'il faut pour rédiger : budget du niveau, section de CHANGELOG.md de la version, fichiers de site/, diff depuis le tag semver précédent et statuts (structure détaillée dans castor site:context). Claude ne lit que ce contexte, puis rédige dans site/ en respectant le budget du niveau :

Niveau Ce qui est attendu Limite vérifiée
patch Corriger ce que le changelog a rendu faux, rien d'autre. Aucune écriture si rien n'est devenu faux. Aucun fichier ajouté ou supprimé, 30 lignes modifiées au plus.
minor Blocs mis à jour ou ajoutés, mise en page inchangée. Aucun fichier HTML ajouté ou supprimé, 300 lignes modifiées au plus.
major Site quasi nouveau. Pas de limite de lignes, mais une maquette Artifact validée par vous avant toute écriture dans site/. Son URL est enregistrée dans var/claude/release-<version>/maquette-validee.txt (première ligne https://… du fichier).

Ce qui n'entre pas dans le calcul : site/data/ et le contenu des marqueurs kirexo:* (version, date, mémoire, hébergeur, statuts). Ces parties sont produites par site:refresh et site:build : ne les éditez pas à la main. Une ligne réécrite compte pour une, pas pour deux.

Dépasser le budget. Si une nouveauté visible du changelog ne tient pas dans le budget (un nouveau canal de diffusion, une nouvelle extension), Claude vous propose le dépassement et n'écrit rien avant votre réponse. Si vous acceptez, il rédige, puis vous indique d'ajouter --accepte-depassement à la commande de ship. Claude n'ajoute jamais cette option lui-même : c'est elle qui matérialise votre accord. Elle ne change pas la version déjà calculée. Elle ne lève pas non plus l'exigence de maquette d'un major.

Vérifier avant de shipper. Le garde-fou est un script local, sans effet remote :

bash .claude/skills/creer-tag/bin/site-diff-check.sh minor

Il compare site/ (fichiers non suivis compris) au dernier tag semver qui contient site/, applique le budget du niveau, puis lance castor site:build et castor site:check. Il ne touche pas à l'index Git.

Code Signification Que faire
0 Dans le budget, ou dépassement accepté, et site:build + site:check verts. Passer au ship.
1 Erreur : usage, branche autre que release-<version>, site/data/release.json absent ou d'une autre version, échec de site:build ou de site:check. Lire le message ; pour release.json, relancer castor site:refresh --name=<version>.
2 Hors budget sans --accepte-depassement, ou major sans maquette validée (même avec l'option). Réduire les modifications, ou faire valider le dépassement, ou enregistrer l'URL de la maquette.

Le script affiche la référence retenue, les fichiers ajoutés et supprimés, et le nombre de lignes modifiées, par exemple :

› Référence : 0.1.0
› Fichiers ajoutés : 0 · supprimés : 0 · dont HTML ajoutés : 0 · supprimés : 0
› Lignes modifiées (hors site/data/ et contenu des marqueurs) : 42
✓ Dans le budget minor (42 ligne(s) modifiée(s) / 300).

Première release : budget non mesuré

La référence du diff est toujours un tag semver, jamais un ancien tag horodaté, et il doit contenir site/. Tant qu'aucun tag semver ne contient site/ (c'est le cas de la première release, 0.0.1), le budget n'est pas mesuré : le script affiche budget non mesuré (première publication du site) et exige seulement que site:build et site:check passent.

4. Ship (remote)

bash .claude/skills/creer-tag/bin/release.sh 0.2.0 minor

Signature : release.sh <version> <niveau> [--accepte-depassement]. Ajoutez --accepte-depassement seulement si vous avez validé un dépassement de budget à l'étape 3 :

bash .claude/skills/creer-tag/bin/release.sh 0.2.0 minor --accepte-depassement

Le script exige la variable d'environnement GITLAB_TOKEN dans le shell qui le lance : il crée la MR et suit la pipeline par l'API GitLab, avec curl. Il ne passe pas par glab.

Avant toute action, le script refuse une version qui n'est pas semver stricte, un niveau autre que patch, minor ou major, une option inconnue, une branche autre que release-<version> et une section absente de CHANGELOG.md. Il enchaîne ensuite, dans l'ordre :

  1. site-diff-check.sh <niveau> [--accepte-depassement] : un code 2 arrête tout, sans commit, et le script sort en 2 ;
  2. castor audit (filet CVE) ;
  3. commit de CHANGELOG.md et de site/ ;
  4. push de la branche release-<version> ;
  5. MR vers main, assignée, sans squash, avec auto-merge armé. La description mentionne le niveau et, le cas échéant, le dépassement accepté ;
  6. attente du merge, puis d'une pipeline verte sur main ;
  7. castor tag:create --name <version>.

À la fin, la pipeline $CI_COMMIT_TAG (build images, doc, release GitLab, publication du site vitrine) se déclenche automatiquement, comme pour les autres méthodes. La publication du site est décrite dans Publier le site vitrine.

Pourquoi attendre le vert avant de taguer

Le job tag:create exige une pipeline success sur le dernier commit de main (cf. garde-fou). release.sh attend donc le vert post-merge avant d'appeler tag:create --name — sinon le tag serait refusé.

La version étant imposée (forme semver stricte validée par release.sh, par Castor et par le job CI, qui contrôle aussi qu'elle est supérieure à la dernière version), la section de CHANGELOG.md écrite à l'étape 1 porte exactement le nom du tag qui sera posé : pas de décalage entre le contenu commité et le tag.

Le détail bas niveau de la pose du tag (garde-fou, chaîne de jobs déclenchée) est ci-dessous.

Prérequis

  • Vous avez les droits Maintainer ou Owner sur le projet GitLab.
  • La variable CI/CD GITLAB_TOKEN est configurée (cf. Variables CI/CD GitLab) — un Personal Access Token avec le scope write_repository (les project access tokens sont réservés à GitLab Premium/Ultimate).
  • Les images kirexo-base et kirexo-dev existent dans le registry : la pipeline qualité en dépend. Sur une instance neuve, suivre Bootstrapper la pipeline CI, étape 6. kirexo-prod n'a aucun prérequis : elle n'est plus construite sur main, et l'absence de cache ne fait pas échouer le tag (docker pull … || true). L'image kirexo-docs non plus : son job docker:build-docs est needs: [] et tourne automatiquement avant pages sur tag.

Pourquoi passer par une pipeline et pas par git tag en local

git push --tags fonctionnerait, mais ça impose d'avoir une clé SSH ou un PAT configurés sur la machine qui pousse, et ça ne marche pas depuis un environnement où le repo n'est pas cloné en écriture (ex. depuis Claude Code en mode bypassPermissions qui n'a pas la clé de la personne). La pipeline tag:create crée le tag côté serveur via l'API GitLab — l'auteur·rice de la release n'a besoin que de son accès UI ou de glab.

Méthode A — Depuis l'UI GitLab

  1. Aller sur Build → Pipelines → Run pipeline (bouton en haut à droite).
  2. Choisir la branche main.
  3. Ajouter une variable :
  4. Key : CREATE_TAG
  5. Value : true
  6. Type : Variable (pas File).
  7. Cliquer sur Run pipeline.

La pipeline créée ne contient que le job tag:create (stage tag). Tous les autres jobs sont filtrés par leurs rules: — la pipeline CREATE_TAG=true est volontairement isolée pour ne pas dédoubler la pipeline qualité.

Garde-fou : une pipeline verte est exigée sur le dernier commit de main

Avant de créer le tag, tag:create vérifie qu'au moins une pipeline success existe pour le dernier commit de main ($CI_COMMIT_SHA) — typiquement la pipeline de validation jouée au merge. Si aucune pipeline verte n'est trouvée, le job échoue et le tag n'est pas créé. Le but : ne jamais figer une release sur un commit dont la CI est rouge ou encore en cours.

Pour outrepasser ce garde-fou dans un cas exceptionnel, ajouter une seconde variable FORCE_TAG à true (en plus de CREATE_TAG) :

Key Value
CREATE_TAG true
FORCE_TAG true

Avec FORCE_TAG=true, le statut de pipeline n'est plus vérifié : le tag est créé inconditionnellement. À réserver aux situations où l'on sait que le commit est sain mais que la pipeline n'a pas (re)tourné.

Méthode B — Depuis le CLI avec glab

glab ci run --branch main --variables "CREATE_TAG:true"

Le retour de glab affiche l'ID et l'URL de la pipeline créée — suivez-la via glab ci get -p <id> ou directement dans l'UI.

Pour outrepasser le garde-fou de pipeline verte (cf. Méthode A), ajouter --variables "FORCE_TAG:true" :

glab ci run --branch main --variables "CREATE_TAG:true" --variables "FORCE_TAG:true"

Méthode C — Avec Castor

La cible castor tag:create est un raccourci autour de l'appel glab de la Méthode B — c'est la voie la plus courte pour poser un tag à la main. Le workflow recommandé (skill /creer-tag) s'appuie sur cette cible pour la pose finale du tag, après avoir mis à jour le CHANGELOG.md.

castor tag:create

Pour outrepasser le garde-fou de pipeline verte (cf. Méthode A), ajouter --force — équivalent de FORCE_TAG=true. La cible affiche alors un warning avant de déclencher la pipeline :

castor tag:create --force

Sans --name, le job pose la patch suivante de la dernière version semver (0.0.1 s'il n'en existe aucune). Pour imposer la version — une mineure par exemple —, passer --name avec une version semver stricte — c'est ce que fait le skill /creer-tag une fois le CHANGELOG.md mergé :

castor tag:create --name 0.1.0

La valeur est transmise au job via la variable CI TAG_NAME (cf. Ce que fait tag:create). Un nom mal formé (1.2, v0.1.0, 01.0.0…) lève une erreur côté Castor avant même de déclencher la pipeline. La monotonie (version supérieure à la dernière), elle, n'est vérifiée que par le job CI : les tags locaux peuvent être en retard sur le serveur.

Un simple raccourci, pas une mécanique différente

castor tag:create exécute exactement glab ci run --branch main --variables "CREATE_TAG:true" (plus --variables "TAG_NAME:<nom>" avec --name, et --variables "FORCE_TAG:true" avec --force). Le tag est créé côté serveur GitLab par le job tag:create, à l'identique des méthodes A et B — voir Ce que fait tag:create pour le détail. Prérequis : un glab authentifié (glab auth status), puisque la cible s'appuie sur lui.

Ce que fait tag:create

Le job tourne sur alpine:3 avec GIT_STRATEGY: none (pas besoin de cloner le code — l'API agit côté serveur GitLab) et exécute :

  1. Garde-fou (sauf si FORCE_TAG=true) : interroge GET /projects/:id/pipelines?sha=$CI_COMMIT_SHA&status=success et refuse de taguer (exit 1) si aucune pipeline success n'existe pour le dernier commit de main. Le contrôle est fail-safe : si l'appel API échoue (token invalide, réseau), le compteur retombe à 0 et le job bloque plutôt que de risquer une release non validée.
  2. Lit la dernière version semver du dépôt : liste tous les tags via l'API (paginée, 100 par page), ne garde que les noms ^[0-9]+\.[0-9]+\.[0-9]+$ et les trie numériquement par composante (0.10.0 > 0.9.0). Les anciens tags horodatés YYYYMMDDHHMM et les tags annexes (etape4-*, v*…) sont ignorés.
  3. Détermine le nom du tag :

    • si la variable TAG_NAME est fournie au déclenchement (cas du skill /creer-tag / castor tag:create --name), elle est validée deux fois — un échec fait échouer le job :
      • forme : semver strict sans zéro de tête (^(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)$) ;
      • monotonie : strictement supérieure à la dernière version ; s'il n'en existe aucune, seule 0.0.1 est acceptée ;
    • sinon, le nom est calculé côté serveur : patch suivante de la dernière version (0.0.3 → 0.0.4), ou 0.0.1 s'il n'en existe aucune.

    Imposer TAG_NAME permet au commit taggé de contenir déjà sa section de CHANGELOG.md, écrite sous ce même nom avant la pose du tag (cf. workflow recommandé). 4. Vérifie l'absence d'un tag homonyme (un GET .../repository/tags/${TAG_NAME} ; un 200 arrête le job pour éviter un 409 cryptique au POST). 5. Appelle POST /projects/:id/repository/tags avec ${GITLAB_TOKEN} :

    curl --fail \
      --header "PRIVATE-TOKEN: ${GITLAB_TOKEN}" \
      --data "{\"tag_name\": \"${TAG_NAME}\", \"ref\": \"${CI_DEFAULT_BRANCH}\"}" \
      "${CI_API_V4_URL}/projects/${CI_PROJECT_ID}/repository/tags"
    
  4. Affiche la réponse JSON via jq '{name, target, message}'.

Le --fail de curl fait échouer le job si l'API renvoie un statut HTTP ≥ 400 — typiquement 403 Forbidden si GITLAB_TOKEN n'a pas le scope write_repository, ou 409 Conflict si un tag du même nom a été créé entre le pré-check et le POST.

Ce qui se déclenche ensuite

Dès que GitLab détecte le tag créé, il démarre automatiquement une nouvelle pipeline $CI_COMMIT_TAG. Cette pipeline ne rejoue ni les vérifications qualité ni les tests : ceux-ci ont déjà tourné sur le même SHA dans la pipeline main que tag:create a exigée verte (cf. Optimisation pipeline de tag). Seuls les jobs qui produisent un livrable ou dont le résultat dépend de l'instant T du tag s'exécutent :

Stage Job Effet
quality quality:composer-audit Filet de sécurité rejoué sur le SHA du tag — capture une CVE Composer éventuellement publiée entre le merge et le tag. Si rouge, la pipeline du tag échoue et les jobs docker:* / release:* ne tournent pas.
docker docker:build-base, docker:build-dev Build + push automatique. kirexo-base et kirexo-dev reçoivent :php8.5-alpine + :latest.
docker docker:build-prod, docker:build-prod-arm64 Build natif de kirexo-prod, une jambe par architecture (amd64 sur le runner par défaut, arm64 sur le runner saas-linux-small-arm64). Chaque jambe ne pousse que son tag intermédiaire :$CI_COMMIT_TAG-amd64 ou :$CI_COMMIT_TAG-arm64, non installable. La jambe arm64 est best-effort (allow_failure: true) : rouge ou jamais démarrée (quota de minutes épuisé), elle ne bloque pas la release.
docker docker:manifest-prod Une fois la jambe amd64 verte, assemble l'index (linux/amd64, plus linux/arm64 si sa jambe a tout réussi) et crée kirexo-prod:$CI_COMMIT_TAG (tag de version immuable, cf. Déployer Kirexo en production), :latest et :php8.5-alpine.
docker docker:build-docs, docker:build-supply-chain Build + push des images d'outillage CI consommées au stage suivant (mkdocs pour pages, cosign + syft pour docker:sign-prod et release:sbom).
docker docker:sign-prod Signature keyless cosign de l'index par digest, récursive (index et images de plateforme), puis vérification des références publiées : cinq sans arm64, sept avec (cf. Supply chain et signatures).
release pages Build de la documentation mkdocs en mode strict (via l'image kirexo-docs) et déploiement sur GitLab Pages.
release release:sbom Génération des SBOM SPDX + CycloneDX de kirexo-prod:$CI_COMMIT_TAG, un jeu par architecture publiée (deux fichiers sans arm64, quatre avec).
release release:bundle-render Rendu du bundle d'installation (install/) avec KIREXO_VERSION écrite à la version du tag, plus les SBOM, dans l'artifact release-assets/. Attend docker:manifest-prod.
release release:bundle-publish Envoi des cinq ou sept fichiers dans le Generic Package Registry (paquet kirexo, version = tag). Attend docker:sign-prod.
release release:create Création de la release GitLab avec changelog des commits depuis le tag précédent et cinq liens à permalien stable (cf. Assets de release et permaliens). Sans arm64, la note se termine par une section « Architecture ». Attend release:bundle-publish et docker:sign-prod.
release release:links-arm64 Si arm64 est publié, ajoute à la release les deux liens SBOM linux/arm64 ; sinon, sort sans rien faire. Attend release:create.
maintenance container_scanning + security:container-issue Scan CVE de kirexo-prod:$CI_COMMIT_TAG après l'assemblage de l'index — signal au moment de la release, pas H+24. Une seule architecture est scannée (a priori amd64). Ouvre une issue uniquement si au moins une CVE Critical ou High est remontée (cf. Jobs container_scanning et security:container-issue).

Le tout sans intervention manuelle supplémentaire. docker:build-docs étant dans le stage docker (avant release), l'image de build de la doc est toujours fraîche au moment où pages la consomme — aucun bootstrap manuel n'est nécessaire pour la doc (contrairement à kirexo-base / kirexo-dev, cf. prérequis).

Pourquoi la qualité ne rejoue pas

tag:create refuse de poser le tag si aucune pipeline success n'existe pour le commit ciblé. Le code du tag est donc, par construction, strictement le même SHA qu'une pipeline qualité verte. Rejouer cs-fix, phpstan, tests unitaires ou E2E donnerait exactement le même résultat — pure duplication de minutes runner. Seul quality:composer-audit est conservé sur tag, parce que la base de vulnérabilités évolue indépendamment du code et qu'une CVE peut être publiée entre le merge et le tag.

Vérifier qu'une release est partie

  1. La pipeline CREATE_TAG=true doit être verte. Si le job tag:create échoue avec 403, vérifier le scope write_repository du token (cf. Variables CI/CD GitLab).
  2. La pipeline $CI_COMMIT_TAG apparaît dans la liste des pipelines avec le nom du tag (0.0.1) — cliquer dessus pour suivre les jobs Docker et release.
  3. La release apparaît dans Deploy → Releases avec le changelog généré et cinq ou sept liens d'assets : trois dans la catégorie « Packages » (compose.yaml, .env.example, README.md), deux SBOM linux/amd64 (SPDX et CycloneDX) et, si arm64 est publié, deux SBOM linux/arm64. Sans arm64, la note de release se termine par une section « Architecture » qui le signale. Le .env.example publié doit contenir KIREXO_VERSION=<tag> :

    curl -fsSL https://gitlab.com/shaurifr/kirexo/-/releases/0.0.1/downloads/.env.example | grep '^KIREXO_VERSION='
    
    4. La doc est mise à jour sur https://doc.kirexo.app/ (cf. Configurer le domaine GitLab Pages). 5. Les images Docker sont visibles dans Deploy → Container Registry : kirexo-base et kirexo-dev avec les tags :php8.5-alpine et :latest ; kirexo-prod avec :php8.5-alpine, :latest et le tag de version :0.0.1 (le nom du tag Git), plus le tag intermédiaire :0.0.1-amd64 et, si la jambe arm64 a poussé, :0.0.1-arm64 ; kirexo-docs avec le seul tag :latest. Le tag de version désigne un index :

    docker buildx imagetools inspect registry.gitlab.com/shaurifr/kirexo/kirexo-prod:0.0.1
    

    La sortie liste une entrée Platform: linux/amd64 et, si arm64 est publié, une entrée Platform: linux/arm64. Sans entrée arm64, la note de release porte la section « Architecture ». Un tag -amd64 sans tag :0.0.1 signale une pipeline de tag interrompue avant docker:manifest-prod : la version n'est pas installable. Un tag -arm64 sans entrée arm64 dans l'index signale une jambe arm64 tombée après son push.

Cas d'erreur

Le job tag:create échoue avec 401 Unauthorized

Le GITLAB_TOKEN est absent ou expiré. Régénérer le token (Settings → Access Tokens), mettre à jour la variable CI/CD (Settings → CI/CD → Variables) et relancer le job.

Le job tag:create échoue avec 403 Forbidden

Le token n'a pas le scope write_repository, ou son rôle est inférieur à Maintainer. Régénérer un token avec les bons droits.

Le job tag:create échoue sans appeler l'API des tags (garde-fou)

Le job s'arrête avant la création du tag parce qu'aucune pipeline success n'existe pour le dernier commit de main. Causes typiques : la pipeline de validation est encore en cours, a échoué, ou n'a jamais tourné sur ce commit. Attendre qu'une pipeline passe au vert sur main, puis relancer CREATE_TAG=true. En cas exceptionnel (commit que l'on sait sain mais sans pipeline rejouée), outrepasser avec FORCE_TAG=true (cf. Méthode A / Méthode B) ou castor tag:create --force (cf. Méthode C).

Le job tag:create refuse TAG_NAME

Deux messages possibles :

  • TAG_NAME invalide (…) — version sémantique attendue MAJEUR.MINEUR.CORRECTIF (ex. 0.0.1). : la valeur n'est pas semver stricte (préfixe v, zéro de tête, suffixe -rc1, ancien format horodaté…). Corriger la valeur.
  • TAG_NAME … n'est pas supérieur à la dernière version … : une version égale ou supérieure a déjà été posée, souvent parce que les tags locaux étaient en retard au moment de prepare.sh. Supprimer la branche release-<version>, puis relancer prepare.sh : il rafraîchit les tags et recalcule la version. S'il n'existe encore aucune version, le message indique que la première release doit être 0.0.1.

Le job tag:create signale un tag déjà existant

Message Le tag … existe déjà — abandon (choisis une version supérieure). : la version demandée est déjà posée. Relancer avec une version supérieure (ou sans TAG_NAME pour laisser le job calculer la patch suivante).

Pipeline $CI_COMMIT_TAG jamais déclenchée

Vérifier que le tag a bien été créé : glab repo view --web puis onglet Tags, ou directement via l'API. Seuls les tags de la forme MAJEUR.MINEUR.CORRECTIF déclenchent une pipeline : un tag v0.0.1, un ancien tag horodaté ou un tag annexe poussé à la main n'en déclenche aucune (cf. Pipeline GitLab CI). Si le tag est bien au format semver et qu'aucune pipeline n'est partie, vérifier le workflow:rules dans .gitlab-ci.yml — la règle $CI_COMMIT_TAG doit y figurer.

Le job pages échoue en mode strict

mkdocs détecte un lien cassé, un snippet manquant ou un avertissement de plugin. Reproduire localement avec castor docs:build (qui passe les mêmes options) pour identifier la cause exacte avant de retagger.

Voir aussi