Jetons npm stage-only : les preuves à conserver lors de la séparation entre automatisation et approbation finale
Séparer le droit de l'intégration continue (CI) à générer un paquet de celui de le rendre public auprès des utilisateurs clarifie la responsabilité finale de la publication. Cependant, ajouter un simple bouton d'approbation ne fait pas disparaître les risques pesant sur la chaîne d'approvisionnement logicielle. Il faut d'abord définir ce que la personne chargée de l'approbation doit vérifier.
GitHub a annoncé le 18 septembre qu'il est désormais possible de sélectionner une permission d'écriture stage-only pour les granular access tokens de npm. Le flux de travail permet à l'automatisation de soumettre une version en attente d'examen, puis aux mainteneurs d'en approuver la publication via une authentification 2FA. Voici une explication distinguant les modifications officielles des recommandations opérationnelles de la rédaction.
Bloquer la publication directe ne signifie pas retirer les droits d'écriture
D'après la documentation officielle, ce jeton permet d'exécuter npm stage publish, mais la publication directe via npm publish est rejetée. Cette restriction s'applique même si une configuration de contournement de la 2FA (bypass-2FA) est activée pour l'automatisation. Il ne s'agit pas d'une modification automatique du comportement des jetons existants, mais d'une option à adopter volontairement.
Il faut toutefois noter que d'autres permissions d'écriture sur les paquets subsistent, comme le déplacement des dist-tags ou l'obsolescence (deprecation) d'une version. Le libellé stage-only ne doit pas être interprété comme un jeton en lecture seule ou inoffensif. La portée des paquets autorisés, l'emplacement de stockage des secrets, les entités autorisées à les utiliser et les procédures de révocation doivent toujours être gérés rigoureusement.
Définir le lot de publication à comparer par l'approbateur
Ce qui suit n'est pas une obligation imposée par npm, mais une recommandation opérationnelle destinée aux petites équipes. Dans chaque demande d'approbation, regroupez le commit source, le paquet et la version cibles, les résultats des tests, la liste des fichiers inclus dans le paquet ainsi qu'un résumé des modifications. Si l'approbateur doit reconstituer les preuves en consultant plusieurs journaux d'exécution de la CI, la revue risque de devenir un simple clic de pure forme.
L'examen du code source et celui des fichiers distribués sont deux démarches distinctes. Des fichiers absents du dépôt peuvent être intégrés lors de l'étape de compilation (build), ou des fichiers nécessaires peuvent être oubliés. L'équipe peut formaliser le principe selon lequel le dossier de revue est constitué à partir des artefacts réellement soumis, et que toute modification de l'artefact après revue exige une nouvelle procédure d'examen.
Il reste un état d'attente après le voyant vert de la CI
Si votre automatisation actuelle considérait le succès d'une commande comme la fin du déploiement, il convient d'abord de revoir la façon d'exprimer les états. Séparez la soumission effectuée, l'attente d'approbation et la publication terminée, en enregistrant les éléments probants de chaque étape. Dans les notifications, indiquer l'étape actuelle et le responsable assigné s'avère plus utile aux opérateurs qu'un simple message annonçant un succès.
À titre d'exemple fictif, si une CI nocturne soumet une nouvelle version mais que le responsable ne l'examine que le lendemain, aucune annonce de sortie destinée aux utilisateurs ne doit être diffusée au moment de la soumission. Ne déclenchez la mise à jour de la documentation ou les annonces qu'après la confirmation de publication définie par l'équipe. Il est également nécessaire de convenir à l'avance de la personne qui traite les demandes en attente et du moment où les anciennes soumissions doivent être nettoyées.
Valider la transition sur un paquet de faible envergure
Actuellement, les prérequis indiqués dans le guide officiel comprennent un paquet npm existant, les droits de publication sur ce paquet, une authentification 2FA configurée sur le compte, ainsi que npm CLI 11.15.0 ou supérieur et Node.js 22.14.0 ou supérieur. Avant d'engager la migration, consultez la documentation la plus récente et vérifiez les versions exécutées sur vos runners.
Il est recommandé de commencer par limiter la portée du jeton sur un unique paquet à faible impact, puis de s'entraîner sur l'ensemble du cycle : soumission en staging, revue par un mainteneur et vérification du résultat publié. Prévoir un repli immédiat vers un ancien jeton aux permissions plus larges en cas d'échec priverait cette séparation de tout son sens. Le retard pris dans une approbation doit pouvoir être géré comme un état normal du processus.
Questions à examiner vis-à-vis du trusted publishing
npm propose également le trusted publishing reposant sur OIDC. Il convient d'abord d'évaluer si cette approche correspond à vos environnements de CI pris en charge et aux modalités d'approbation de votre équipe ; rien n'impose de considérer les jetons stage-only comme la solution ultime pour toutes les organisations. Pour les automatisations qui doivent continuer à utiliser des jetons, cela offre une option de transition progressive.
L'annonce officielle fixe pour objectif janvier 2027 pour la suppression de la publication directe avec des jetons contournant la 2FA (bypass-2FA). Plutôt que de spéculer sur tous les détails d'implémentation définitifs, il est plus pragmatique de dresser dès maintenant la liste des workflows concernés et de désigner les responsables de la migration. Surveillez les annonces officielles ultérieures pour d'éventuels ajustements de calendrier.
Au moment de décider de l'adoption
Cet article ne prétend pas refléter un consensus général de la communauté ni une baisse chiffrée des incidents. Il propose des procédures opérationnelles vérifiables en s'appuyant sur le comportement officiel de cette nouvelle fonctionnalité. Savoir expliciter précisément ce qui relève de l'automatisation et ce qui nécessite une vérification humaine constitue le point de départ pour décider de son adoption.
Dès aujourd'hui, vous pouvez inventorier les emplacements utilisant des jetons de publication, consigner les critères qui certifient la fin d'une publication et définir les preuves requises pour valider une approbation. Ce n'est qu'en traitant de front la restriction des privilèges et la rigueur de l'examen que l'étape de staging apportera un bénéfice réel.