Saltar al contenido

CI más rápido para workspaces de pnpm en GitHub Actions

Última actualización · Publicado por primera vez

En un workspace de pnpm puede obtener gran parte de la velocidad de un sistema de compilación sin ninguna herramienta adicional: almacene en caché el store de pnpm, instale una sola vez y ejecute los scripts solo en los paquetes que han cambiado con pnpm --filter "...[origin/main]". Esta guía explica los filtros, la configuración de checkout que necesitan y cuándo añadir Turborepo o Nx encima.

Instale una vez y almacene el store en caché

steps:
  - uses: actions/checkout@v6
    with:
      fetch-depth: 0
  - uses: pnpm/action-setup@v6
  - uses: actions/setup-node@v7
    with:
      node-version: 22
      cache: pnpm
  - run: pnpm install --frozen-lockfile

Instale en la raíz del repositorio. pnpm instala y enlaza todos los paquetes del workspace en una sola pasada. Los detalles sobre las rutas y claves del store están en cómo almacenar pnpm en caché en GitHub Actions.

Ejecute solo los paquetes modificados

El parámetro --filter de pnpm acepta un selector de cambios desde una referencia. Según la documentación de filtrado de pnpm (consultada en octubre de 2026):

# packages changed since origin/main
pnpm --filter "[origin/main]" test

# changed packages plus everything that depends on them
pnpm --filter "...[origin/main]" test

# changed packages plus their dependencies
pnpm --filter "[origin/main]..." build

Use "...[origin/main]" para test y build en CI. Un cambio en packages/ui debe volver a probar apps/web, que depende de él. Los ... delante del selector añaden los dependientes.

Dos opciones útiles de la misma documentación:

  • --test-pattern="test/*" evita añadir dependientes cuando solo han cambiado archivos de prueba, así un cambio en un test no vuelve a probar todo.
  • --changed-files-ignore-pattern="**/README.md" ignora los cambios que no importan, como la documentación.
pnpm --filter "...[origin/main]" \
  --changed-files-ignore-pattern="**/*.md" \
  run test

La documentación indica que la referencia se compara con el merge base, el commit donde se bifurcó su rama, y que en un clon superficial sin el merge base pnpm compara directamente con la referencia. El selector requiere Git 2.24 o posterior. Las imágenes alojadas en GitHub y compiler.dev incluyen una versión más reciente de Git.

Profundidad de fetch

origin/main debe existir localmente. El checkout solo obtiene el commit de fusión de la PR, por lo que la referencia de la rama base puede faltar. Dos soluciones:

- uses: actions/checkout@v6
  with:
    fetch-depth: 0

o obtenga solo lo necesario:

- uses: actions/checkout@v6
  with:
    fetch-depth: 1
- run: git fetch --no-tags --depth=200 origin ${{ github.base_ref }}

Un fetch superficial funciona si 200 commits cubren el merge base; si no, los resultados serán menos precisos. El historial completo es más sencillo y, con filter: tree:0 en el checkout, sigue siendo rápido.

En eventos push a main, origin/main es el commit actual, por lo que el filtro no selecciona nada. Use "...[HEAD^1]" para los push o ejecute la suite completa en main y los runs filtrados solo en las PR.

Paralelismo dentro de pnpm

pnpm ejecuta los scripts en orden topológico y puede paralelizar. Con -r:

pnpm -r --workspace-concurrency=8 run test

--workspace-concurrency tiene 4 como valor por defecto. En una máquina de 8 núcleos, 8 es un buen punto de partida. Combínelo con filtros:

pnpm --filter "...[origin/main]" --workspace-concurrency=8 run test

Ejecute con --if-present para que los paquetes sin el script se omitan en lugar de fallar. Use --workspace-concurrency=1 solo para depurar problemas de orden.

Reparto entre jobs

pnpm no distribuye el trabajo entre máquinas. Use una matrix de GitHub por paquete o grupo de tareas:

jobs:
  test:
    runs-on: ubuntu-latest
    strategy:
      fail-fast: false
      matrix:
        package: [web, api, worker]
    steps:
      - uses: actions/checkout@v6
        with:
          fetch-depth: 0
      - uses: pnpm/action-setup@v6
      - uses: actions/setup-node@v7
        with:
          node-version: 22
          cache: pnpm
      - run: pnpm install --frozen-lockfile --filter "${{ matrix.package }}..."
      - run: pnpm --filter "${{ matrix.package }}" test

pnpm install --filter con name... instala solo ese paquete y sus dependencias, lo que acorta cada job. Los puntos después del nombre indican dependencias; los puntos antes (...name) indican dependientes, los paquetes que dependen de él. Equilibre la matrix para que ningún job domine; consulte sharding de tests para dividir una suite grande y la calculadora de shards para saber cuántos shards compensan.

Cuándo añadir Turborepo o Nx

Los filtros de pnpm indican qué paquetes han cambiado, pero no almacenan en caché la salida de las tareas. Si el mismo paquete se recompila desde cero en cada PR, una caché de tareas ayuda: Turborepo y Nx calculan hashes de las entradas y reutilizan las salidas, en local y en remoto. Consulte CI más rápido para Turborepo y CI más rápido para Nx. Funcionan bien sobre workspaces de pnpm y usan los mismos patrones packages de pnpm-workspace.yaml.

Un workflow completo

name: CI
on:
  push:
    branches: [main]
  pull_request:

concurrency:
  group: ci-${{ github.ref }}
  cancel-in-progress: true

jobs:
  check:
    runs-on: [self-hosted, Linux, compiler-ci]   # or ubuntu-latest
    timeout-minutes: 20
    steps:
      - uses: actions/checkout@v6
        with:
          fetch-depth: 0
      - uses: pnpm/action-setup@v6
      - uses: actions/setup-node@v7
        with:
          node-version: 22
          cache: pnpm
      - run: pnpm install --frozen-lockfile
      - name: PR: changed packages only
        if: github.event_name == 'pull_request'
        run: |
          pnpm --filter "...[origin/${{ github.base_ref }}]" \
            --workspace-concurrency=8 run --if-present lint test build
      - name: main: everything
        if: github.event_name == 'push'
        run: pnpm -r --workspace-concurrency=8 run --if-present lint test build

El bloque concurrency cancela las ejecuciones reemplazadas en la misma rama, lo que también ahorra minutos; consulte reducir la factura de GitHub Actions. En compiler.dev, la línea runs-on asigna el job a una máquina de 8 vCPU a $0.008 por minuto, con las cachés de dependencias listas; consulte precios.

La comprobación de tipos y el linting suelen ser la parte lenta de un monorepo de TypeScript; la caché para ellos se explica en acelerar un monorepo de TypeScript.

Errores comunes

  1. No existe la referencia origin/main. El filtro no encuentra nada o encuentra todo.
  2. Olvidar los dependientes. [origin/main] sin ... omite los paquetes afectados a través de dependencias.
  3. Filtrar la instalación. Filtre la instalación solo si está seguro de que cada job necesita un subconjunto; una dependencia omitida aparece como un error confuso.
  4. Cambios en la raíz. Un cambio en pnpm-lock.yaml o en la configuración raíz afecta a todos los paquetes. Considere ejecutar la suite completa cuando cambien.

Preguntas frecuentes

¿Cómo decide pnpm que un paquete ha cambiado?

Mediante git diff desde la referencia, asignado a los directorios de cada paquete. pnpm también considera que un paquete ha cambiado cuando cambia una versión de catálogo que usa en pnpm-workspace.yaml.

¿Puedo usar los filtros de pnpm con Turborepo?

Sí, pero Turborepo tiene su propio --filter con una sintaxis similar. Use uno u otro en cada comando.

¿Es seguro usar pnpm install --filter?

Lo es para jobs de matrix bien acotados. Si tiene dudas, instale todo; el store en caché lo hace barato.

¿Qué fetch-depth debo usar?

0 es seguro. Un fetch superficial de la rama base funciona si cubre el merge base.

Ejecute esta build de monorepo en compiler.dev Sin tarjeta · 200 minutos gratuitos

Pruébelo gratis