Tokens stage-only de npm: la evidencia que se debe conservar al separar la automatización de despliegues y la aprobación final
Separar el permiso de la integración continua (CI) para empaquetar una biblioteca del permiso para publicarla a los usuarios aporta mayor claridad sobre la responsabilidad final del lanzamiento. Sin embargo, añadir un simple botón de aprobación no elimina los riesgos en la cadena de suministro. Primero es necesario definir qué debe verificar la persona responsable de la aprobación.
GitHub anunció el 18 de septiembre que ahora es posible seleccionar permisos de escritura stage-only en los granular access tokens de npm. En este flujo, la automatización envía una versión a un estado pendiente de revisión y los mantenedores aprueban su publicación mediante 2FA. A continuación se detallan los cambios oficiales junto con propuestas prácticas de la redacción para implementarlos en operaciones reales.
Bloquear la publicación directa no equivale a eliminar los permisos de escritura
Según la información oficial, estos tokens permiten ejecutar npm stage publish, pero rechazan la publicación directa a través de npm publish. Esta restricción se aplica incluso si existen ajustes para eludir la 2FA en automatizaciones. No se trata de una función que altere de forma automática el comportamiento de los tokens existentes, sino de una opción que se adopta voluntariamente.
Un aspecto crucial a tener en cuenta es que aún se conservan otros permisos de escritura sobre el paquete, como mover etiquetas dist-tag o marcar versiones como obsoletas (deprecation). No debe interpretarse el término stage-only como si fuera un token de solo lectura o totalmente inofensivo. Sigue siendo indispensable gestionar el alcance de paquetes permitidos, la ubicación donde se almacenan los secretos, quién los utiliza y los procedimientos para revocarlos.
Definir el paquete de evidencias que la persona aprobatoria debe comparar
Lo que se expone a continuación no es una configuración obligatoria de npm, sino una propuesta operativa para equipos reducidos. En cada solicitud de aprobación, incluya el commit de origen, el paquete y versión de destino, los resultados de las pruebas, la lista de archivos incluidos en el paquete y un resumen de cambios. Si quien aprueba tiene que recopilar evidencias dispersas en múltiples registros de la CI, la revisión corre el riesgo de convertirse en un trámite mecánico de un solo clic.
En particular, revisar el código fuente y revisar los archivos distribuidos son tareas distintas. Durante el proceso de compilación podrían incluirse archivos inexistentes en el repositorio o bien omitirse archivos necesarios. El equipo puede establecer el principio de generar materiales de revisión basados en los artefactos reales que se envían y, si estos artefactos cambian tras la revisión, tratarlos como un nuevo objeto de evaluación.
Existe un estado pendiente incluso después de una CI en verde
Si las automatizaciones anteriores consideraban el éxito de un comando como el fin del lanzamiento, es momento de cambiar la forma en que se expresan los estados. Esto implica diferenciar entre envío completado, pendiente de aprobación y publicación finalizada, registrando las evidencias de verificación para cada etapa. En las notificaciones resulta mucho más útil para los operadores indicar la fase actual y la persona asignada en lugar de una simple palabra como «éxito».
Como ejemplo hipotético, si una CI nocturna envía una nueva versión pero la persona responsable la revisará al día siguiente, no se debe emitir un anuncio de lanzamiento para los usuarios en el momento del envío. Asegúrese de que la documentación o los avisos se publiquen solo después de la confirmación formal establecida por el equipo. También conviene acordar de antemano quién revisará la cola si se acumulan entregas y cuándo se limpiarán los envíos anteriores.
Validar la migración con un paquete pequeño
Entre los requisitos iniciales de la documentación oficial actual figuran un paquete de npm existente, permisos para publicar paquetes, 2FA activada en la cuenta, npm CLI 11.15.0 o superior y Node.js 22.14.0 o superior. Antes de realizar la migración real, es imprescindible consultar la documentación actualizada y revisar las versiones instaladas en los ejecutores (runners) en uso.
Se recomienda acotar primero el alcance del token en un paquete de bajo impacto y ensayar todo el proceso: envío a staging, revisión por parte de los mantenedores y confirmación del resultado de la publicación. Si ante un fallo se recurre de inmediato a un token previo con permisos amplios, los límites establecidos pierden su valor. Es necesario estar preparados para tratar los retrasos en la aprobación como un estado operativo normal.
Cuestiones a considerar al compararlo con trusted publishing
npm también ofrece trusted publishing mediante OIDC. Lo primero que conviene evaluar es si esta opción se adapta a los entornos de CI compatibles y al flujo de aprobación del equipo, ya que no hay motivo para generalizar los tokens stage-only como la solución definitiva para todos los casos. Para aquellas automatizaciones que deban seguir empleando tokens, esto puede entenderse como una nueva alternativa para migrar de forma escalonada.
El anuncio oficial establece enero de 2027 como fecha objetivo para retirar la publicación directa mediante tokens con elusión de 2FA (bypass-2FA). En lugar de especular sobre todos los detalles concretos de implementación, resulta más práctico catalogar desde ahora los flujos de trabajo afectados y designar responsables para la transición. Cualquier modificación en los plazos deberá comprobarse en futuros comunicados oficiales.
Al decidir si adoptarlo
Este artículo no pretende reflejar un consenso generalizado de la comunidad ni cuantificar reducciones en la tasa de incidentes. Su objetivo es proponer un procedimiento operativo verificable a partir del comportamiento oficial de la nueva funcionalidad. Poder delimitar qué tareas corresponden a la automatización y cuáles requieren verificación humana es el punto de partida para decidir su adopción.
Lo que se puede hacer hoy mismo es identificar dónde se emplean actualmente los tokens de lanzamiento, documentar las condiciones que certifican una publicación completada y definir las evidencias necesarias para cada aprobación. Solo combinando la restricción de permisos con la calidad de la revisión logrará la fase de staging aportar un valor real.