Flujos de Release Simplificados con Changesets
Publicar paquetes npm no debería requerir scripts personalizados, incrementos manuales de versión, o recordar qué paquetes cambiaron desde tu último release. Sin embargo, muchos equipos aún improvisan procesos de release frágiles que fallan en los peores momentos.
Changesets resuelve esto capturando la intención del release en el momento de la contribución, y luego automatizando el resto. Este artículo cubre cómo construir un flujo de trabajo moderno de release con Changesets—incluyendo publicación confiable de npm, versionado de monorepo con Changesets, y releases de paquetes con GitHub Actions—sin la carga de mantenimiento.
Puntos Clave
- Changesets captura la intención del release en el momento de la contribución mediante archivos markdown que especifican los paquetes afectados y los tipos de incremento semver
- La publicación confiable de npm con tokens OIDC elimina las credenciales de larga duración y añade procedencia criptográfica a tus paquetes
- El versionado de monorepo se vuelve manejable con opciones de configuración como
linked,fixedyupdateInternalDependencies - Los errores comunes de CI incluyen problemas de permisos, conflictos de automatización de PR, y changesets olvidados
El Flujo de Trabajo Central de Release con Changesets
El flujo de trabajo sigue tres fases:
- Los contribuidores añaden archivos changeset describiendo qué cambió y qué tan significativo es (patch, minor, major)
- CI crea un PR de versionado que agrega todos los changesets en incrementos de versión y entradas de changelog
- Hacer merge del PR activa la publicación a npm con la procedencia adecuada
Cada changeset es un archivo markdown en .changeset/ que contiene frontmatter especificando los paquetes afectados y el tipo de incremento semver, más un resumen legible por humanos. Cuando existen múltiples changesets, Changesets calcula el incremento de versión más alto necesario por paquete—dos cambios minor no se convierten en dos incrementos minor.
Para monorepos, esto importa significativamente. Changesets maneja automáticamente las actualizaciones de dependencias internas cuando un paquete del workspace depende de otro que está siendo liberado.
Releases de Paquetes con GitHub Actions: El Enfoque Moderno
La mayoría de los tutoriales muestran workflows usando secretos NPM_TOKEN. Ese enfoque funciona pero conlleva riesgos de seguridad—los tokens de larga duración pueden filtrarse y requieren rotación manual.
La publicación confiable de npm usando tokens OIDC es ahora el método preferido. En lugar de almacenar credenciales, tu workflow de GitHub Actions solicita un token de corta duración directamente de npm durante el paso de publicación. El token existe solo para ese job y no puede ser extraído o reutilizado.
Para habilitar esto:
- Vincula tu paquete npm a tu repositorio de GitHub en la configuración del paquete en npm
- Configura tu workflow con el permiso
id-token: write - Asegúrate de que la procedencia esté habilitada (npm puede generarla automáticamente para publicadores confiables, o mediante la bandera
--provenanceen CLIs más recientes)
La procedencia de npm añade una certificación criptográfica que prueba que el paquete fue construido desde un commit específico en tu repositorio. Los usuarios pueden verificar exactamente qué código fuente produjo el artefacto publicado.
Limitaciones actuales a conocer: la publicación confiable de npm requiere repositorios públicos. Los repositorios privados aún necesitan el enfoque legacy de NPM_TOKEN. Además, la changesets/action oficial tiene soporte evolutivo para OIDC—consulta la documentación actual para los patrones de integración más recientes.
Discover how at OpenReplay.com.
Versionado de Monorepo con Changesets
Changesets fue diseñado para monorepos desde el principio. Las opciones clave de configuración en .changeset/config.json controlan el comportamiento multi-paquete:
linked: Agrupa paquetes que siempre deben compartir el mismo número de versiónfixed: Similar a linked, pero todos los paquetes se incrementan juntos incluso si solo uno cambióupdateInternalDependencies: Controla si los dependientes reciben incrementos patch cuando sus dependencias se actualizan
Cuando un contribuidor ejecuta el CLI de changeset en un monorepo, selecciona qué paquetes afecta su cambio. El PR de versionado entonces muestra exactamente qué paquetes se liberarán y en qué versiones.
Errores Comunes de CI
Los problemas de permisos causan la mayoría de las fallas de workflow. El token de GitHub necesita acceso de escritura para crear PRs y hacer push de tags. Para la publicación en npm, asegúrate de que tu token (o configuración OIDC) tenga derechos de publicación para todos los paquetes en tu scope.
Los conflictos de automatización de PR ocurren cuando las reglas de protección de rama bloquean al bot de hacer push de commits de versión. O permite que el bot de GitHub Actions omita la protección o usa una cuenta de bot dedicada con los permisos apropiados.
El orden de publicación multi-paquete importa cuando los paquetes dependen entre sí. Changesets maneja esto automáticamente, pero las fallas de red a mitad de publicación pueden dejar tu monorepo en un estado inconsistente. La changesets/action incluye lógica de reintento, pero entender este modo de falla ayuda con la recuperación.
Los changesets olvidados son el error más común de los contribuidores. El bot de Changeset comenta en los PRs que faltan changesets, pero también puedes añadir verificaciones de CI que fallen cuando se requieren changesets pero están ausentes.
Estructurando tu Workflow Hoy
La mayoría de los equipos ejecutan la action de Changesets en cada push a main. La action abre o actualiza un PR de “Version Packages” cuando existen changesets no liberados, o publica paquetes cuando se hace merge del PR de versión.
Esto crea una cadencia natural de release: haz merge de features durante la semana, luego haz merge del PR de versión cuando estés listo para publicar. Sin edición manual de versiones, sin olvidar actualizar changelogs, sin publicar los paquetes equivocados.
Conclusión
Un flujo de trabajo de release con Changesets bien configurado elimina la sobrecarga cognitiva de los releases de paquetes. Los contribuidores declaran la intención por adelantado, CI maneja la coordinación, y la publicación confiable de npm asegura artefactos seguros y verificables.
Comienza con una configuración de paquete único para entender el flujo, luego extiende a monorepos según sea necesario. La inversión inicial de configuración se amortiza rápidamente en ansiedad reducida de release y menos momentos de “ups, versión incorrecta”.
Preguntas Frecuentes
Changesets funciona bien tanto con paquetes únicos como con monorepos. Para paquetes únicos, el flujo de trabajo es más simple ya que solo rastreas un paquete. Comienza con una configuración de paquete único para aprender los conceptos básicos, luego escala a monorepos cuando sea necesario. El flujo de trabajo central de añadir changesets, crear PRs de versión y publicar permanece igual independientemente del número de paquetes.
El bot de Changeset comenta automáticamente en los pull requests que faltan archivos changeset. También puedes configurar verificaciones de CI para que fallen cuando se requieren changesets pero están ausentes. Esto previene que los cambios se fusionen sin la documentación de release adecuada, aunque puedes marcar algunos PRs como que no requieren changesets para actualizaciones solo de documentación.
Cuando marcas un paquete con un incremento de versión major, Changesets verifica qué otros paquetes dependen de él. La opción de configuración updateInternalDependencies controla si los dependientes reciben automáticamente incrementos patch. Para paquetes estrechamente acoplados, usa las opciones linked o fixed para asegurar que los números de versión permanezcan sincronizados entre paquetes relacionados.
No, la publicación confiable de npm con tokens OIDC actualmente requiere repositorios públicos. Para repositorios privados, debes usar el enfoque tradicional de NPM_TOKEN con un token de acceso de larga duración almacenado como secreto del repositorio. Mantén estos tokens seguros y rótalos periódicamente para minimizar los riesgos de seguridad.
Understand every bug
Uncover frustrations, understand bugs and fix slowdowns like never before with OpenReplay — the open-source session replay tool for developers. Self-host it in minutes, and have complete control over your customer data. Check our GitHub repo and join the thousands of developers in our community.
