Setup d'un projet pour le flow release Spektrum

Checklist des prérequis CI/CD et settings GitLab à configurer une fois côté projet avant que les composants release puissent fonctionner.

Variables CI/CD

À configurer dans Settings → CI/CD → Variables.

Variable	Type	Visibilité	Requise par	Description
RELEASE_TOKEN	Variable	Protected + Masked	release-tag, publish-docker	Project Access Token avec scope write_repository. Sans ça, le push du tag annoté échoue : CI_JOB_TOKEN ne peut pas pousser sur une ref protégée.
NPM_TOKEN	Variable	Protected + Masked	(jobs publish-npm projet-spécifiques)	Token du registry npm interne avec droit de publish. Non requis par les composants actuels du repo.

Comment créer RELEASE_TOKEN

1. Settings → Access Tokens (au niveau projet, pas user).
2. Créer un token avec :
   • Scope : write_repository
   • Role : Maintainer (ou plus)
   • Expiration : selon la politique du projet.
3. Settings → CI/CD → Variables : ajouter RELEASE_TOKEN avec la valeur du token, cocher Protected et Masked.

Settings projet GitLab

Merge requests

Settings → Merge requests → Merge method : "Merge commit" ou "Fast-forward" uniquement.

Settings → Merge requests → Squash commits when merging : Do not allow (ou Allow mais s'assurer que les MR release/* ne sont jamais squashées).

Pourquoi : un squash réécrit le sujet de commit en Merge branch 'release/…'-style avec perte du numéro de version explicite. Les rules: des composants ne matchent plus → le tag n'est pas poussé → le publish ne se déclenche pas.

Branches et tags protégés

Settings → Repository → Protected branches : la branche par défaut doit être protégée. C'est ce qui fait que RELEASE_TOKEN (protected) est exposé aux jobs qui tournent sur cette branche.

Settings → Repository → Protected tags : protéger * ou au minimum [0-9]*.[0-9]*.[0-9]*. Sans ça :

• les variables Protected ne sont pas exposées aux pipelines de tag (donc release-detect ne peut pas lire RELEASE_TOKEN si besoin) ;
• n'importe qui peut pousser un tag arbitraire et déclencher une release.

Rôle autorisé à pousser : Maintainer (ou laisser No one si seul le job CI doit pouvoir tagger via RELEASE_TOKEN).

Project Badges (optionnel mais recommandé)

Settings → General → Badges : ajouter les badges qui pointent sur les artefacts SVG produits par release-badges (ou par publish-docker si on utilise celui-ci à la place) :

Badge name	Link URL	Badge image URL
prod	https://gitlab.internal.spektrum-suisse.ch/<group>/<project>/-/releases	https://gitlab.internal.spektrum-suisse.ch/<group>/<project>/-/jobs/artifacts/<default-branch>/raw/badges/prod.svg?job=release-badges
staging	(idem)	(idem avec staging.svg)

Remplacer <default-branch> par la branche par défaut du projet (souvent main ou develop), et release-badges par publish-docker-prod / publish-docker-staging si tu utilises publish-docker.

Fichiers projet attendus

.release-it.json

À la racine du projet. Doit contenir au minimum :

{
  "trunkBranch": "main"
}

Aligner trunkBranch sur la branche par défaut GitLab. Si le fichier manque, l'exécuter avec :

npx --yes @spektrum/release-util@latest init

.gitlab-ci.yml

Au minimum, déclarer les stages que les composants utilisent et les inclure. Voir release-flow.md pour choisir les composants, et chaque components/<nom>.md pour le snippet d'include.

Pré-requis runner (pour publish-docker seulement)

Les jobs publish-docker ne font pas de docker login. Le runner GitLab qui exécute ces jobs doit :

• avoir un daemon Docker disponible (les jobs Spektrum tournent sur des runners shell avec Docker installé, pas via docker:dind) ;
• être pré-authentifié au registry cible (typiquement ~/.docker/config.json provisionné au niveau machine).

Si le push échoue avec denied: requested access to the resource is denied, c'est presque toujours un problème de config docker sur le runner, pas un problème de YAML.

Voir aussi

• release-flow.md : le flow et le modèle mental.
• troubleshooting.md : si quelque chose ne fonctionne pas après ce setup.

Contributors

No contributors

Changelog

No recent changes