npm Trusted Publishing con GitHub Actions: publicar paquetes sin NPM_TOKEN

Esta guía explica cómo publicar paquetes npm desde GitHub Actions con npm Trusted Publishing, OpenID Connect (OIDC) y npm provenance, sin guardar un NPM_TOKEN de larga duración en GitHub Secrets.

Si estás depurando npm publish E404 Not Found, Access token expired or revoked, tokens npm vencidos, fallos de publicación en GitHub Actions, errores 404 al publicar paquetes scoped o dudas sobre npm publish --access public, usa la configuración y la lista de comprobación de este artículo.

Conclusión principal

Para publicar paquetes npm desde GitHub Actions, es mejor usar npm Trusted Publishing que guardar un NPM_TOKEN permanente.

Una configuración correcta requiere cuatro condiciones:

Añadir un Trusted Publisher en la configuración del paquete npm, con la organización o usuario de GitHub, el repositorio y el nombre exacto del workflow.
Usar un runner hospedado por GitHub. Los self-hosted runners no son compatibles con npm Trusted Publishing.
Configurar permissions: id-token: write para que GitHub Actions pueda emitir un token OIDC.
Usar una versión reciente de Node/npm compatible con el flujo OIDC. Node 24 con npm latest es una base práctica.

Este artículo se basa en la migración real de n2n-memory desde publicación con token hacia Trusted Publishing. La configuración técnica mostrada aquí fue verificada.

Cuándo usar esta guía

Esta guía es útil si buscas:

Cómo configurar npm Trusted Publishing
Cómo publicar un paquete npm desde GitHub Actions
Cómo publicar un paquete npm sin NPM_TOKEN
Cómo configurar npm OIDC publishing
Cómo resolver npm publish E404 Not Found - PUT
Cómo resolver Access token expired or revoked
Por qué GitHub Actions falla después de vencer un token npm
Cómo activar npm provenance
Por qué un paquete scoped devuelve 404 al publicar
Cuándo usar npm publish --access public

Por qué reemplazar NPM_TOKEN por Trusted Publishing

El flujo tradicional guarda NPM_TOKEN en GitHub Secrets, define NODE_AUTH_TOKEN en CI y ejecuta npm publish. Funciona, pero introduce costes de operación y riesgos de seguridad:

Los tokens caducan, se revocan o requieren rotación manual.
Un token filtrado puede ser difícil de limitar.
Con 2FA puede hacer falta gestionar bypass o automation tokens.
En varios repositorios y paquetes, la gestión de secretos se vuelve confusa.

Trusted Publishing funciona de otra manera. npm confía en un workflow específico dentro de un repositorio GitHub específico. Cuando ese workflow ejecuta npm publish, GitHub Actions proporciona una credencial OIDC de corta duración. npm valida la identidad del workflow, permite la publicación y puede generar metadata de provenance.

En una frase: Trusted Publishing hace que npm confíe en el workflow de GitHub que publica, no en un token permanente.

Configuración en npm: añadir un Trusted Publisher

Abre la página de acceso del paquete:

https://www.npmjs.com/package/<package-name>/access

Por ejemplo:

https://www.npmjs.com/package/n2n-memory/access

Entra en Settings, busca Trusted Publishers, elige GitHub Actions y completa:

Campo	Valor
Organization or user	`n2ns`, la cuenta u organización de GitHub
Repository	`n2n-memory`, el nombre del repositorio
Workflow filename	`publish.yml`, solo el nombre del archivo
Environment name	Déjalo vacío salvo que uses GitHub Environment

Detalles importantes:

Workflow filename debe ser solo el nombre del archivo, por ejemplo publish.yml.
No uses la ruta completa .github/workflows/publish.yml.
Organization or user, Repository y Workflow filename deben coincidir exactamente con GitHub.
Estos campos distinguen mayúsculas y minúsculas.
Pulsa Save changes después de editar; si no, la configuración no se aplica.

Workflow recomendado de GitHub Actions

Este .github/workflows/publish.yml es una base verificada:

name: Publish Package

on:
  push:
    tags:
      - 'v*'
  workflow_dispatch:

permissions:
  id-token: write
  contents: read

jobs:
  publish:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - uses: actions/setup-node@v4
        with:
          node-version: '24'
          registry-url: 'https://registry.npmjs.org'

      - name: Upgrade npm
        run: npm install -g npm@latest

      - run: npm ci

      - run: npm run check

      - run: npm publish --access public

Puntos clave:

permissions: id-token: write es obligatorio para publicar con OIDC.
runs-on: ubuntu-latest usa un runner hospedado por GitHub. npm Trusted Publishing no soporta self-hosted runners.
node-version: '24' evita problemas de soporte incompleto en versiones antiguas de npm CLI.
npm install -g npm@latest asegura una versión reciente de npm.
registry-url debe apuntar explícitamente a https://registry.npmjs.org.
Los paquetes scoped públicos deben usar:

npm publish --access public

No configures NODE_AUTH_TOKEN para npm publish, o npm podría usar la ruta antigua basada en token en vez de OIDC Trusted Publishing.

Configuración recomendada de package.json

Incluye la URL real del repositorio y la configuración de publicación pública:

{
  "name": "n2n-memory",
  "version": "1.2.2",
  "repository": {
    "type": "git",
    "url": "git+https://github.com/n2ns/n2n-memory.git"
  },
  "publishConfig": {
    "access": "public",
    "provenance": true
  }
}

Notas:

repository.url debe apuntar al repositorio real de GitHub.
npm provenance valida el origen de publicación. Una URL incorrecta puede causar fallos o metadata incoherente.
Los paquetes scoped públicos deben conservar publishConfig.access: "public".
publishConfig.provenance: true activa explícitamente npm provenance.

Flujo completo de publicación

Después de configurar todo:

Añade y guarda el Trusted Publisher en npm.
Haz commit y push de .github/workflows/publish.yml:

git add .github/workflows/publish.yml package.json
git commit -m "chore: configure npm trusted publishing"
git push

Confirma que la versión de package.json no fue publicada antes.
Crea y sube un tag:

git tag v1.2.2
git push origin v1.2.2

Espera a que termine el job Publish Package en GitHub Actions.
Verifica la publicación en npm:

npm view n2n-memory dist-tags.latest
npm view n2n-memory versions --json

Si dist-tags.latest apunta a la nueva versión, la publicación fue correcta.

Solución de problemas

Por qué npm publish devuelve E404 Not Found

Un error típico se ve así:

npm error code E404
npm error 404 Not Found - PUT https://registry.npmjs.org/@scope%2fpackage - Not found
npm error 404 '@scope/[email protected]' is not in this registry.

En npm publish, esto normalmente significa que no hay permiso correcto de publicación o que la identidad del Trusted Publisher no coincide. Revisa en orden:

El Trusted Publisher fue guardado con Save changes
Organization or user coincide exactamente con el owner de GitHub
Repository coincide exactamente con el repositorio
Workflow filename es solo publish.yml, sin ruta
El archivo workflow está en .github/workflows/publish.yml
El workflow usa un runner hospedado por GitHub
El workflow incluye permissions: id-token: write
Node es 24 y npm fue actualizado a latest
El paquete scoped público usa npm publish --access public

Cómo resolver Access token expired or revoked

Si todavía aparece esto después de migrar a Trusted Publishing:

Access token expired or revoked

npm CLI probablemente sigue usando la ruta antigua de autenticación con token. Revisa:

Elimina NODE_AUTH_TOKEN del paso npm publish.
Elimina escrituras de .npmrc con token.
Actualiza Node/npm.
Deja de usar actions o scripts antiguos que inyecten token.

Con Trusted Publishing bien configurado, el workflow no necesita NPM_TOKEN.

Por qué npm whoami no valida OIDC

npm whoami usa autenticación tradicional. No demuestra que Trusted Publishing OIDC esté bien configurado.

La validación fiable es ejecutar el workflow de publicación y confirmar que npm publish termina correctamente.

Por qué puede fallar workflow_dispatch

npm comprueba la identidad del workflow que realmente publica. Mantén npm publish dentro del mismo publish.yml registrado como Trusted Publisher. Evita publicar desde workflows anidados o reusable workflows salvo que hayas verificado que la identidad registrada sigue coincidiendo.

Por qué puede fallar tras transferir el owner del paquete

Transferir el owner de un paquete npm no actualiza automáticamente Trusted Publisher. Después de una transferencia, verifica:

La cuenta npm actual tiene permiso de escritura sobre el paquete.
Trusted Publisher apunta al owner y repositorio actuales de GitHub.
El workflow filename coincide con npm.
package.json tiene el repository.url actual.

Checklist mínimo

Antes de publicar, confirma:

El paquete npm tiene un Trusted Publisher guardado
Workflow filename es publish.yml, solo nombre de archivo
El workflow está en .github/workflows/publish.yml
El workflow incluye permissions: id-token: write
El workflow usa un runner hospedado por GitHub, como ubuntu-latest
El workflow usa node-version: '24'
El workflow ejecuta npm install -g npm@latest
npm publish no usa NODE_AUTH_TOKEN
package.json repository.url apunta al repositorio actual de GitHub
package.json incluye publishConfig.access: "public"
La versión del paquete aún no fue publicada

FAQ

npm Trusted Publishing todavía necesita NPM_TOKEN?

No. Trusted Publishing usa identidad OIDC de corta duración de GitHub Actions en vez de un NPM_TOKEN permanente.

npm Trusted Publishing soporta self-hosted runners?

No. El workflow de publicación debe usar un runner hospedado por GitHub, como ubuntu-latest.

Qué debe tener Workflow filename?

Solo el nombre del archivo, por ejemplo publish.yml. No uses .github/workflows/publish.yml.

Por qué usar --access public en paquetes scoped?

Los paquetes scoped públicos pueden tratarse como privados si no se indica el acceso. Usa:

npm publish --access public

También conserva esto en package.json:

"publishConfig": {
  "access": "public",
  "provenance": true
}

Trusted Publishing y provenance son lo mismo?

No. Trusted Publishing valida quién publica mediante GitHub Actions OIDC. Provenance registra de dónde viene el paquete. Son funciones distintas que funcionan bien juntas.