CI/CD

pubm está diseñado para comportarse bien tanto en terminales locales como en runners de CI. El punto clave es que el pipeline normal de pubm ya sabe cómo consumir los changesets pendientes durante el versionado, así que no necesitas un paso separado de pubm changesets version solo para preparar CI.

pubm init puede generar workflows de CI durante el setup. El asistente ofrece crear .github/workflows/release.yml (publicación activada por tags) y .github/workflows/changeset-check.yml (aplicación del requisito de changesets en PRs) para que no tengas que escribirlos a mano.

Modelo de release recomendado

Usa dos fases:

1. ejecuta pubm --mode ci --phase prepare localmente o en un job de release controlado
2. publica desde CI con pubm --mode ci --phase publish

pubm --mode ci --phase prepare

pubm --mode ci --phase publish

Qué hace la preparación de CI

pubm --mode ci --phase prepare no es solo una verificación de tokens. Ejecuta el pipeline de release hasta justo antes de la publicación real:

• recopila los tokens de registry y las credenciales de plugins
• sincroniza opcionalmente con GitHub Secrets
• ejecuta las comprobaciones de prerrequisitos y condiciones requeridas
• ejecuta tests y build salvo que se omitan
• consume los changesets pendientes durante el versionado cuando existen
• crea el commit de release y hace push de los tags y los cambios de rama
• simula la publicación en lugar de realizarla realmente

Por eso no necesitas ejecutar pubm patch --dry-run después de la preparación de CI.

Variables de entorno requeridas

En CI, proporciona los tokens de registry mediante variables de entorno:

Variable	Registry
NODE_AUTH_TOKEN	npm
JSR_TOKEN	jsr
CARGO_REGISTRY_TOKEN	crates.io

Los plugins también pueden declarar sus propias credenciales requeridas. pubm las recopila y resuelve automáticamente. Durante --ci-prepare, pide los valores faltantes y los sincroniza con GitHub Secrets. Durante --phase publish, solo lee los valores resueltos desde el entorno y falla si falta cualquier credencial obligatoria.

Por ejemplo, @pubm/plugin-brew requiere:

Variable	Propósito
PUBM_BREW_GITHUB_TOKEN	GitHub PAT usado para hacer push de actualizaciones de fórmulas y abrir pull requests para Homebrew.

Sincronizar GitHub Secrets

Si ya guardaste tokens localmente mediante una ejecución de preparación de CI, súbelos a GitHub Secrets con:

pubm secrets sync
pubm secrets sync --registry npm,jsr

Estructura de ejemplo en GitHub Actions

name: Release

on:
  push:
    tags:
      - "v*"
      - "@*"

jobs:
  publish:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - uses: pnpm/action-setup@v4

      - uses: actions/setup-node@v4
        with:
          node-version: 24

      - run: pnpm install --frozen-lockfile
      - run: pubm --mode ci --phase publish
        env:
          NODE_AUTH_TOKEN: ${{ secrets.NODE_AUTH_TOKEN }}
          JSR_TOKEN: ${{ secrets.JSR_TOKEN }}
          CARGO_REGISTRY_TOKEN: ${{ secrets.CARGO_REGISTRY_TOKEN }}

Releases snapshot en CI

Usa pubm snapshot para publicar versiones de previsualización desde CI sin crear un release real. Es útil para probar cambios en paquetes antes de un release completo.

- name: Publish snapshot
  run: npx pubm snapshot
  env:
    NODE_AUTH_TOKEN: ${{ secrets.NODE_AUTH_TOKEN }}

En monorepos, puedes filtrar los paquetes a incluir en el snapshot:

- name: Publish snapshot
  run: npx pubm snapshot --filter @acme/core --filter @acme/react
  env:
    NODE_AUTH_TOKEN: ${{ secrets.NODE_AUTH_TOKEN }}

Las versiones snapshot se publican con un número de versión temporal derivado de la versión base, el tag, el timestamp y el hash del commit. No afectan a la gestión normal de versiones de release.

Problemas habituales en CI

Checkout superficial

Las operaciones que dependen de tags e historial necesitan información completa de Git. Usa fetch-depth: 0 para los jobs de release.

Faltan tokens de registry

pubm no puede pedir datos interactivos en CI. Si falta un token, la ejecución falla.

Desajuste del token de 2FA de npm

Usa tokens compatibles con automatización para publicar en CI.

La salida de build no está presente en contents

Si publicas desde dist/, asegúrate de que el workflow realmente cree dist/ antes de pubm --mode ci --phase publish.

Assets de GitHub Release

Si tu proyecto usa releaseAssets en pubm.config.ts, pubm --mode ci --phase publish ejecuta el asset pipeline y sube los artefactos a GitHub Release automáticamente.

Requisito de GITHUB_TOKEN

La creación del GitHub Release y la subida de assets usan la API de GitHub. Proporciona GITHUB_TOKEN o un token de grano fino con permiso contents: write. El token es necesario para toda creación de GitHub Release, no solo para subir assets:

- run: pubm --mode ci --phase publish
  env:
    NODE_AUTH_TOKEN: ${{ secrets.NODE_AUTH_TOKEN }}
    GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

GitHub Actions inyecta GITHUB_TOKEN como secreto integrado en cada ejecución del workflow. No necesitas crearlo manualmente, solo pasarlo por el entorno.

Los outputs de build deben existir antes de subir

El asset pipeline se ejecuta después del build step. Asegúrate de que tu workflow produzca los binarios o artefactos necesarios, por ejemplo en platforms/*/bin/, antes de que se ejecute pubm --mode ci --phase publish. Si un patrón glob configurado no coincide con ningún archivo al subir, pubm lo trata como error.

Ejemplo con assets de release

name: Release

on:
  push:
    tags:
      - "v*"

jobs:
  publish:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - uses: actions/setup-node@v4
        with:
          node-version: 24

      - run: npm ci
      - run: npm run build       # Debe producir platforms/*/bin/mytool
      - run: pubm --mode ci --phase publish
        env:
          NODE_AUTH_TOKEN: ${{ secrets.NODE_AUTH_TOKEN }}
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

Flujo de trabajo de version bump basado en PR

Como alternativa a hacer push directamente de los commits de version bump, pubm puede crear un pull request en su lugar. Esto es útil cuando tu rama base está protegida o quieres un paso de revisión antes de publicar.

Actívalo en la configuración:

export default defineConfig({
  createPr: true,
});

O pasa el flag en tiempo de ejecución:

pubm --create-pr

Cuando createPr está habilitado:

• pubm crea una rama pubm/version-packages-* con el commit de version bump
• se hace push de la rama y se abre un PR contra la rama base
• el PR se etiqueta automáticamente con no-changeset para omitir la comprobación de changeset
• cuando el PR se fusiona, el workflow de release existente se activa normalmente mediante el push del tag

pubm también cae automáticamente en modo PR cuando falla un push directo a una rama protegida, por lo que no es necesario configurar createPr explícitamente si solo quieres el comportamiento de respaldo.

Comprobación de changeset (validación de PR)

Usa la GitHub Action syi0808/pubm-actions para exigir que cada PR incluya un changeset. pubm init genera este workflow automáticamente cuando los changesets están habilitados.

name: Changeset Check

on:
  pull_request:
    types: [opened, synchronize, reopened, labeled, unlabeled]

permissions:
  contents: read
  pull-requests: write

jobs:
  changeset-check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - uses: syi0808/pubm-actions@v1
        with:
          skip-label: no-changeset

La action detecta nuevos archivos .pubm/changesets/*.md en el diff del PR, valida su formato y publica un comentario con el resultado. Añade la etiqueta no-changeset para omitir la comprobación en PRs que no necesitan changeset (docs, config de CI, etc.).

Siguientes pasos

• Lee la guía Troubleshooting para diagnosticar fallos.
• Lee la CLI Reference para ver todos los flags de ejecución usados en CI.
• Lee la guía Release Assets para configurar releaseAssets en tu proyecto.