El trusted publishing de npm ya puede mover dist-tags mediante OIDC

GitHub anunció el 30 de septiembre de 2026 que el trusted publishing (publicación de confianza) de npm ya puede gestionar dist-tags. Son las etiquetas como latest que deciden qué versión de un paquete instala la gente. Los pipelines de publicación pueden mover esas etiquetas con un token de inicio de sesión de corta duración en lugar de un token de acceso de npm almacenado. Eso elimina un motivo habitual para guardar un secreto de npm de larga duración dentro de un sistema de CI.

El permiso es opcional (opt-in). Empieza desactivado en todas las configuraciones, antiguas o nuevas, así que nadie obtiene la capacidad de mover latest sin haberla pedido.

Qué son el trusted publishing y los dist-tags

El trusted publishing permite que un trabajo de CI, como un flujo de trabajo de GitHub Actions, publique en npm sin una contraseña ni un token almacenados. El trabajo demuestra quién es mediante OIDC, siglas de OpenID Connect, una forma estándar de emitir tokens de identidad de corta duración. El registro de npm comprueba ese token con una configuración que preparó el propietario del paquete y luego permite la acción.

Un dist-tag es un puntero con nombre a una versión de un paquete. La etiqueta latest es la que siguen la mayoría de las instalaciones. Los proyectos suelen añadir otras, como next o beta, para versiones de prueba. Hasta ahora, el trusted publishing podía publicar un paquete, pero no mover estos punteros, así que los equipos guardaban un token de larga duración para ese paso.

Qué permite el nuevo permiso

Cada configuración de trusted publishing tiene ahora un ajuste llamado "Allow npm dist-tag", según el registro de cambios de GitHub. Cuando está activado, el trabajo de CI puede añadir, eliminar y promover dist-tags. La documentación de npm enumera los comandos correspondientes: npm dist-tag ls, npm dist-tag add y npm dist-tag rm.

GitHub subraya el valor predeterminado. "Está desactivado por defecto tanto en las configuraciones nuevas como en las existentes, así que ninguna configuración obtiene automáticamente una nueva capacidad", dice el registro de cambios.

El permiso es independiente de la publicación. Según la documentación, se puede autorizar a una configuración a hacer staging de paquetes y a gestionar dist-tags sin autorizarla a ejecutar npm publish. Añade que las configuraciones creadas después del 3 de septiembre de 2026 pueden hacer staging de paquetes automáticamente, pero el acceso a los dist-tags todavía hay que activarlo a mano.

Una regla es importante para la seguridad. Un cambio de dist-tag se permite "si el token OIDC entrante coincide con cualquiera de las configuraciones que tienen el permiso activado", escribe GitHub. Por tanto, cada configuración con la casilla marcada es una vía más para mover latest.

Requisitos y límites

La documentación de npm fija estos mínimos:

Requisito	Lo que dice la documentación de npm
npm CLI para dist-tags mediante OIDC	11.21.0 o posterior
npm CLI para trusted publishing en general	11.5.1 o posterior
Node.js	22.14.0 o posterior
GitHub Actions	Solo runners alojados por GitHub
GitLab CI/CD	Solo runners compartidos de GitLab.com
CircleCI	Solo CircleCI en la nube
Runners autoalojados	Aún no compatibles

La documentación dice que los runners autoalojados "están previstos para futuras versiones". Las fuentes difieren sobre la compatibilidad con servicios de CI. Una publicación en DEV Community de un desarrollador llamado Leo también menciona Buddy y Jenkins, este último mediante plugins, pero la propia documentación de npm solo enumera los tres servicios anteriores.

Por qué los dist-tags son un objetivo

Mover un dist-tag es tan poderoso como publicar. La publicación de Leo califica el control de los dist-tags como un riesgo grave para la cadena de suministro, porque un atacante que pueda reescribir latest puede dirigir cada nueva instalación a una versión dañina. Las versiones maliciosas son un patrón real: en agosto, versiones envenenadas del crate de Rust arrayref ejecutaron una carga remota durante las compilaciones.

Leo también advierte de un fallo humano. Los equipos que se topan con una publicación bloqueada pueden marcar la casilla en todas las configuraciones para que el problema desaparezca. La publicación recomienda, en cambio, una única configuración dedicada a las publicaciones con una coincidencia estricta: un archivo de flujo de trabajo concreto, un entorno protegido y un paso de aprobación manual.

Qué significa esto para los desarrolladores

Actualiza primero la npm CLI en tu trabajo de publicación. Los cambios de dist-tags mediante OIDC necesitan npm 11.21.0 o posterior y Node.js 22.14.0 o posterior. Una CLI más antigua en una imagen de CI fijada fallará aunque el ajuste esté activado.

Activa el permiso en un solo lugar. Como cualquier configuración coincidente puede mover latest por sí sola, actívalo en tu configuración de publicación y déjalo desactivado en las configuraciones de staging y de prueba. Revisa la lista después de cada cambio.

Ajusta bien la configuración. Vincúlala al archivo de flujo de trabajo exacto que genera las versiones y exige un entorno protegido con un paso de aprobación. Así, ni un flujo de trabajo de pull request ni un trabajo secundario comprometido podrán mover tus etiquetas.

Borra el token antiguo cuando el cambio funcione. El objetivo de esta novedad es dejar de guardar secretos de npm de larga duración en la CI. Después de que una publicación salga bien mediante OIDC, elimina el token sobrante de los secretos de tu CI y revócalo en npm.

Conserva un token solo donde sea imprescindible. Si compilas en runners autoalojados, el trusted publishing todavía no te cubre. Limita ese token a los paquetes que necesita y rótalo de forma periódica hasta que npm admita runners autoalojados.

Revisa tus etiquetas después de cada publicación. Ejecuta npm dist-tag ls en tu paquete y confirma que latest apunta a donde esperas. Es una comprobación de dos segundos que detecta tanto errores como ataques.