Dépannage / FAQ
Symptômes courants et leur résolution. Pour la politique de fond (hotfix, correction en avant), voir RELEASING.md.
release dit que je suis en retard sur origin/<trunk>. Vous l'êtes. La CLI ne tire jamais à votre place. git pull --ff-only puis réessayer. Si vous avez divergé (local et distant ont chacun des commits que l'autre n'a pas), réconcilier à la main — généralement rebase ou merge depuis origin — puis réessayer.
release dit que trunkBranch ne correspond pas au défaut distant. Quelqu'un a renommé la branche par défaut distante (ex. master → main) et votre .release-it.json est obsolète. Soit mettre à jour trunkBranch dans la config, soit corriger le défaut d'origin avec git remote set-head origin -a. La CLI est volontairement stricte ici — expédier depuis la mauvaise branche est silencieux et coûteux.
release dit que la branche existe déjà. Un run précédent est allé assez loin pour créer la branche mais n'a pas nettoyé — souvent parce que le push a échoué ou que vous avez fait Ctrl-C. Supprimer la branche locale (git branch -D release/...) et, si elle a atteint origin, supprimer aussi la ref distante. Puis re-couper. Le suffixe staging avance automatiquement. Si l'orpheline est sur origin, release --env staging --bump la supprime et roule le compteur au-delà.
Le job publish ne s'est pas déclenché après le merge de ma MR de release. La méthode de merge était squash. Le squash réécrit le sujet chore(release): en Merge branch 'release/...' et le rules: du job publish ne matche pas. Désactiver le squash sur les MR release/* et re-couper.
Ma MR de release avait des conflits ; j'ai mergé main dans release/X.Y.Z pour les résoudre, et le job tag a dit « nothing to tag ». Merger main dans la branche de release est la bonne résolution (jamais de rebase) — le commit « Merge branch 'main' into release/X.Y.Z » se retrouve simplement au-dessus du commit chore(release):. Le tagger gère ce cas : il scanne les commits introduits par la MR (HEAD^1..HEAD^2), donc le commit de release est trouvé même enfoui sous le merge de résolution. Si vous voyez encore ce symptôme, le projet épingle une version antérieure de la CLI ; taguer à la main le merge commit sur le trunk :
git tag -a X.Y.Z <merge-commit> -m "Release X.Y.Z" && git push origin X.Y.ZLe push du tag déclenche normalement le pipeline de tag (detect, publish, badges lisent CI_COMMIT_TAG, pas les sujets de commit).
tag a réussi mais npm publish a renvoyé un 401. Soit NPM_TOKEN manque le scope publish, soit l'hôte de votre .npmrc ne correspond pas au registre où le paquet publie réellement. Vérifier que publishConfig.registry dans package.json correspond à l'hôte dans .npmrc.
release-util --version ment dans l'artefact publié. La chaîne de version est embarquée dans le binaire au build. Si le job publish CI lance npm version "$RELEASE_VERSION" --no-git-tag-version --allow-same-version sans rebuild, le bin publié rapporte toujours l'ancienne version. Toujours rebuild après npm version.
Puis-je amender le commit chore(release): pour corriger une typo dans le changelog ? Non. Le tagger CI se base sur le sujet de ce commit ; le réécrire après le merge de la MR corrompt le pipeline de publication. Si le changelog doit être édité, lander un commit de suivi sur le trunk et re-couper.
Un tag staging est cassé. Puis-je le re-taguer de force ? Non. Couper une nouvelle release staging — 1.0.0-staging.2 supplante 1.0.0-staging.1. Le compteur staging est calculé depuis l'union des tags locaux + distants, il avance donc automatiquement.
Comment corriger un bug de production sans livrer le travail en cours sur le trunk ?release-util hotfix — le flux dédié : --start branche hotfix/<X.Y.Z+1> depuis le dernier tag prod, --apply commit/tague/pousse le tag (déploiement direct), --finish ouvre la MR squash de retour vers le trunk. Fix non validé ? Re-committer sur la même branche et relancer --apply puis --finish. Voir commandes.md#hotfix et Hotfixes dans RELEASING.md.
Puis-je sauter le staging pour un hotfix ? Oui, deux options : release-util hotfix (ci-dessus — ne livre que le fix) ou, si le trunk est livrable en l'état, release-util release --env prod directement (livre tout le trunk). À utiliser avec parcimonie — le staging existe parce que valider en production coûte cher.
Et si je veux releaser depuis une branche qui n'est pas le trunk ? Deux exceptions sanctionnées, chacune avec sa commande : un preview de feature (release --env feature, preview en place, pas de MR — voir environnements-et-versioning.md) et un hotfix (hotfix --apply, tague la branche hotfix/*). Tout le reste est le chemin gitflow que la CLI existe pour empêcher. Si le trunk a du travail inachevé qui ne doit pas partir, c'est un problème de santé du trunk : revert, feature-flag — ou hotfix si c'est une correction de production.
Comment nettoyer une feature abandonnée ?release-util cleanup <slug> supprime la branche feature/* sur origin et tous les tags *-<slug>.* (local + origin). Lancer d'abord avec --dry-run pour prévisualiser. En avant seulement — les numéros supprimés sont perdus définitivement.
Pourquoi doctor sort 3 au lieu de 1 ? Pour que les scripts CI distinguent « le projet est dans un mauvais état » (3) de « la commande elle-même a planté » (1). C'est une sentinelle, pas une typo.