Publication de confiance npm

Migre une version GitHub Actions d'un NPM_TOKEN stocké vers la publication de confiance npm. GitHub signe un token OIDC à courte durée de vie pour l'exécution, et npm l'échange contre un token de publication. Elle diagnostique aussi les erreurs trompeuses qu'une migration inachevée produit. À partir de janvier 2027, les tokens granulaires qui contournent l'authentification double facteur ne peuvent plus publier directement (docs npm).

Quand utiliser cette compétence

• L'utilisateur veut supprimer NPM_TOKEN / NODE_AUTH_TOKEN d'un workflow de version ou configurer la publication OIDC ou de provenance.
• Une publication en CI échoue avec ENEEDAUTH, 404 Not Found - PUT https://registry.npmjs.org/... ou E422 ... repository.url.
• Les logs de version affichent npm notice npm tokens that bypass 2FA are being restricted.

Checklist (tous les points doivent être remplis)

Parcourez chaque élément. En manquer un seul produit les erreurs ci-dessus.

1. Permission OIDC : le job de publication a permissions: id-token: write. Si le job n'avait pas de bloc permissions, conservez les scopes dont il a besoin, comme contents: write pour les tags et versions ou pull-requests: write pour les changesets. Ajouter un bloc supprime tous les scopes que vous ne listez pas.
2. npm 11.5.1 ou plus récent exécute la publication. Node 24 l'inclut. Node 22 inclut npm 10, ajoutez donc npm install -g npm@^11.5.1 (ou une version majeure plus récente épinglée) avant de publier. pnpm 10 délègue la publication à npm, la même règle s'applique. Yarn Berry a besoin de 4.10.3+.
3. Aucun token n'atteint l'étape de publication. Supprimez NODE_AUTH_TOKEN, NPM_TOKEN et YARN_NPM_AUTH_TOKEN de l'étape, du job et de l'env du workflow, et supprimez les lignes de script qui écrivent _authToken ou npmAuthToken. npm essaie OIDC en premier mais se rabat sur un token configuré, donc un token oublié maintient l'ancienne authentification en place. Conservez un token en lecture seule uniquement sur les étapes d'installation qui ont besoin de packages privés.
4. actions/setup-node a registry-url: https://registry.npmjs.org.
5. L'repository.url de package.json nomme le même repo GitHub, par exemple git+https://github.com/OWNER/REPO.git, plus directory pour les packages workspace. Une différence donne E422.
6. Un éditeur de confiance existe sur npm pour chaque package (npmjs.com → package → Settings → Trusted publishing), ou avec npm 11.15+ : npm trust github <pkg> --repo OWNER/REPO --file release.yml --allow-publish --yes
   • Le nom du fichier workflow doit correspondre exactement ; il est sensible à la casse et inclut .yml.
   • Pour un workflow réutilisable, utilisez le nom du fichier du workflow appelant, et accordez id-token: write aussi dans l'appelant.
   • Si le job utilise environment:, définissez le même environnement sur l'éditeur de confiance.
   • Un package qui n'existe pas encore doit être publié une fois à la main d'abord.
7. Runner hébergé par GitHub. Les runners auto-hébergés ne peuvent pas utiliser la publication de confiance.

Règles de sécurité

• Déclencheurs non fiables : n'ajoutez jamais id-token: write à un job dans un workflow déclenché par pull_request_target, issue_comment, workflow_run ou discussion. Cela permettrait aux tiers d'échanger un token OIDC et de publier. Déplacez la publication vers release, push (tags) ou workflow_dispatch.
• Essais à vide : les jobs npm publish --dry-run et npm pack ne publient pas, donc ils n'ont besoin ni de id-token ni d'éditeur de confiance.
• L'ancien token : supprimez le secret (gh secret delete NPM_TOKEN) et révoquez-le sur npmjs.com uniquement après que la première version sans token réussisse.

Guide des erreurs

Exemple

jobs:
  publish:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      id-token: write
    steps:
      - uses: actions/checkout@v5
      - uses: actions/setup-node@v6
        with:
          node-version: 24
          registry-url: https://registry.npmjs.org
      - run: npm ci
      - run: npm publish --access public   # no NODE_AUTH_TOKEN

L'automatiser

go-tokenless (MIT) applique cette checklist à un repository existant. Utilisez-le quand l'utilisateur veut que les éditions soient faites automatiquement.

• npx go-tokenless affiche un diff en lecture seule des changements du workflow et package.json, plus les commandes npm trust.
• npx go-tokenless apply écrit les changements.
• Il refuse les cas non sécurisés ci-dessus au lieu de deviner.

Limitations

• Le côté npm (ajouter l'éditeur de confiance, supprimer l'ancien token) nécessite la connexion npm de l'utilisateur avec l'authentification double facteur. Confiez ces étapes à l'utilisateur.
• La publication de confiance couvre GitHub Actions, GitLab.com et CircleCI cloud uniquement.