Simplifiez vos workflows de release avec Changesets

Jan 25, 2026 · 4 min read

Simplifiez vos workflows de release avec Changesets

Publier des packages npm ne devrait pas nécessiter de scripts personnalisés, de mises à jour manuelles de versions, ou de se souvenir quels packages ont changé depuis votre dernière release. Pourtant, de nombreuses équipes assemblent encore des processus de release fragiles qui tombent en panne au pire moment.

Changesets résout ce problème en capturant l’intention de release au moment de la contribution, puis en automatisant le reste. Cet article explique comment construire un workflow de release moderne avec Changesets — incluant la publication de confiance npm (npm trusted publishing), le versioning de monorepo avec Changesets, et les releases de packages via GitHub Actions — sans le fardeau de la maintenance.

Points clés à retenir

Changesets capture l’intention de release au moment de la contribution via des fichiers markdown qui spécifient les packages affectés et les types de bump semver
La publication de confiance npm avec des tokens OIDC élimine les identifiants à longue durée de vie et ajoute une provenance cryptographique à vos packages
Le versioning de monorepo devient gérable avec des options de configuration comme linked, fixed, et updateInternalDependencies
Les pièges CI courants incluent les problèmes de permissions, les conflits d’automatisation de PR, et les changesets oubliés

Le workflow de release Changesets de base

Le workflow suit trois phases :

Les contributeurs ajoutent des fichiers changeset décrivant ce qui a changé et son importance (patch, minor, major)
La CI crée une PR de versioning qui agrège tous les changesets en bumps de version et entrées de changelog
Le merge de la PR déclenche la publication sur npm avec la provenance appropriée

Chaque changeset est un fichier markdown dans .changeset/ contenant un frontmatter qui spécifie les packages affectés et le type de bump semver, plus un résumé lisible par l’humain. Lorsque plusieurs changesets existent, Changesets calcule le bump de version le plus élevé nécessaire par package — deux changements minor ne deviennent pas deux bumps minor.

Pour les monorepos, cela a une importance significative. Changesets gère automatiquement les mises à jour de dépendances internes lorsqu’un package workspace dépend d’un autre qui est en cours de release.

Releases de packages via GitHub Actions : l’approche moderne

La plupart des tutoriels montrent des workflows utilisant des secrets NPM_TOKEN. Cette approche fonctionne mais comporte des risques de sécurité — les tokens à longue durée de vie peuvent fuiter et nécessitent une rotation manuelle.

La publication de confiance npm (npm trusted publishing) utilisant des tokens OIDC est désormais la méthode privilégiée. Au lieu de stocker des identifiants, votre workflow GitHub Actions demande un token à courte durée de vie directement à npm pendant l’étape de publication. Le token n’existe que pour ce job et ne peut pas être extrait ou réutilisé.

Pour activer cela :

Liez votre package npm à votre dépôt GitHub dans les paramètres du package npm
Configurez votre workflow avec la permission id-token: write
Assurez-vous que la provenance est activée (npm peut la générer automatiquement pour les éditeurs de confiance, ou via le flag --provenance sur les CLI plus récents)

La provenance npm ajoute une attestation cryptographique prouvant que le package a été construit à partir d’un commit spécifique dans votre dépôt. Les utilisateurs peuvent vérifier exactement quel code source a produit l’artefact publié.

Limitations actuelles à connaître : la publication de confiance npm nécessite des dépôts publics. Les dépôts privés nécessitent toujours l’approche legacy NPM_TOKEN. De plus, l’action officielle changesets/action a un support évolutif pour OIDC — consultez la documentation actuelle pour les derniers patterns d’intégration.

Versioning de monorepo avec Changesets

Changesets a été conçu pour les monorepos dès le départ. Les options de configuration clés dans .changeset/config.json contrôlent le comportement multi-packages :

linked : groupe les packages qui doivent toujours partager le même numéro de version
fixed : similaire à linked, mais tous les packages bumpent ensemble même si un seul a changé
updateInternalDependencies : contrôle si les dépendants reçoivent des bumps patch lorsque leurs dépendances se mettent à jour

Lorsqu’un contributeur exécute la CLI changeset dans un monorepo, il sélectionne quels packages sa modification affecte. La PR de versioning montre alors exactement quels packages seront releasés et à quelles versions.

Pièges CI courants

Les problèmes de permissions causent la plupart des échecs de workflow. Le token GitHub nécessite un accès en écriture pour créer des PR et pousser des tags. Pour la publication npm, assurez-vous que votre token (ou configuration OIDC) a les droits de publication sur tous les packages dans votre scope.

Les conflits d’automatisation de PR se produisent lorsque les règles de protection de branche bloquent le bot de pousser des commits de version. Soit autorisez le bot GitHub Actions à contourner la protection, soit utilisez un compte bot dédié avec les permissions appropriées.

L’ordre de publication multi-packages compte lorsque les packages dépendent les uns des autres. Changesets gère cela automatiquement, mais les échecs réseau en cours de publication peuvent laisser votre monorepo dans un état incohérent. L’action changesets/action inclut une logique de retry, mais comprendre ce mode d’échec aide à la récupération.

Les changesets oubliés sont l’erreur de contributeur la plus courante. Le bot Changeset commente les PR manquant de changesets, mais vous pouvez également ajouter des vérifications CI qui échouent lorsque des changesets sont requis mais absents.

Structurer votre workflow aujourd’hui

La plupart des équipes exécutent l’action Changesets à chaque push sur main. L’action ouvre ou met à jour une PR “Version Packages” lorsque des changesets non releasés existent, ou publie les packages lorsque la PR de version est mergée.

Cela crée une cadence de release naturelle : mergez des fonctionnalités tout au long de la semaine, puis mergez la PR de version lorsque vous êtes prêt à livrer. Pas d’édition manuelle de version, pas d’oubli de mise à jour des changelogs, pas de publication des mauvais packages.

Conclusion

Un workflow de release Changesets bien configuré supprime la charge cognitive des releases de packages. Les contributeurs déclarent l’intention en amont, la CI gère la coordination, et la publication de confiance npm assure des artefacts sécurisés et vérifiables.

Commencez avec une configuration single-package pour comprendre le flux, puis étendez aux monorepos selon les besoins. L’investissement initial de configuration est rapidement rentabilisé par la réduction de l’anxiété de release et moins de moments “oups, mauvaise version”.

FAQs

Changesets fonctionne bien avec les packages uniques et les monorepos. Pour les packages uniques, le workflow est plus simple puisque vous ne suivez qu'un seul package. Commencez avec une configuration single-package pour apprendre les bases, puis passez aux monorepos lorsque nécessaire. Le workflow de base d'ajout de changesets, de création de PR de version, et de publication reste le même quel que soit le nombre de packages.

Le bot Changeset commente automatiquement les pull requests qui manquent de fichiers changeset. Vous pouvez également configurer des vérifications CI pour échouer lorsque des changesets sont requis mais absents. Cela empêche les changements d'être mergés sans documentation de release appropriée, bien que vous puissiez marquer certaines PR comme ne nécessitant pas de changesets pour les mises à jour de documentation uniquement.

Lorsque vous marquez un package avec un bump de version majeure, Changesets vérifie quels autres packages en dépendent. L'option de configuration updateInternalDependencies contrôle si les dépendants reçoivent automatiquement des bumps patch. Pour les packages étroitement couplés, utilisez les options linked ou fixed pour garantir que les numéros de version restent synchronisés entre les packages liés.

Non, la publication de confiance npm avec des tokens OIDC nécessite actuellement des dépôts publics. Pour les dépôts privés, vous devez utiliser l'approche traditionnelle NPM_TOKEN avec un token d'accès à longue durée de vie stocké comme secret de dépôt. Gardez ces tokens sécurisés et effectuez leur rotation périodiquement pour minimiser les risques de sécurité.

Understand every bug

Uncover frustrations, understand bugs and fix slowdowns like never before with OpenReplay — the open-source session replay tool for developers. Self-host it in minutes, and have complete control over your customer data. Check our GitHub repo and join the thousands of developers in our community.