CI más rápido para monorepos de Nx en GitHub Actions
Última actualización
El CI más rápido con Nx hace tres cosas: ejecuta solo los proyectos afectados (nx affected), reutiliza resultados mediante una caché remota y reparte el trabajo restante entre varias máquinas. Esta guía profundiza en Nx más que la guía general de Nx y Turborepo, e incluye la configuración de git que puede romper en silencio las ejecuciones de affected.
Paso 1: ejecuciones solo de lo afectado
nx affected compara dos commits y ejecuta las tareas únicamente para los proyectos que han cambiado o que dependen de algo que sí cambió. Necesita una base y un head. La acción nrwl/nx-set-shas las calcula por usted.
jobs:
main:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v6
with:
fetch-depth: 0
filter: tree:0
- uses: actions/setup-node@v7
with:
node-version: 22
cache: npm
- run: npm ci
- uses: nrwl/nx-set-shas@v5
- run: npx nx affected -t lint test build
Según el README de nx-set-shas (consultado en octubre de 2026), la acción exporta NX_BASE y NX_HEAD para el job y también expone base y head como salidas del paso. En un pull request, la base es el merge base con main. En un push a main, es el último commit cuyo workflow se completó correctamente, de modo que un commit fallido no oculta sus cambios en la siguiente ejecución. Si no encuentra ninguno, recurre a HEAD~1, salvo que establezca error-on-no-successful-workflow: true.
El requisito de fetch-depth
actions/checkout descarga un solo commit por defecto. Con un único commit no hay base contra la que comparar, y nx affected o bien falla o considera todo como afectado. El README de nx-set-shas indica que necesita todas las ramas y commits para que Nx tenga una base con la que comparar, por eso el workflow usa fetch-depth: 0.
filter: tree:0 crea un clon parcial sin blobs, lo que mantiene barato el historial completo: se descargan los metadatos de los commits al inicio y el contenido de los archivos bajo demanda. En repositorios muy grandes, esto suele tardar segundos en lugar de un minuto.
Cambie la base por defecto
Nx también lee defaultBase en nx.json (normalmente main). Manténgalo sincronizado con el nombre de su rama principal; de lo contrario, las ejecuciones de affected compararán contra la referencia equivocada.
Paso 2: caché remota
La caché local solo ayuda si el mismo runner ve los mismos archivos. En GitHub Actions, cada job arranca limpio, así que necesita una caché remota para reutilizar los resultados de las tareas entre ejecuciones, ramas y miembros del equipo.
La documentación de Nx (consultada en octubre de 2026) conecta un workspace con npx nx-cloud onboard connect-workspace, que escribe nxCloudId en nx.json. Para la autenticación en CI, describe los tokens de acceso de solo lectura y de lectura y escritura en su guía de tokens de acceso para CI. Use un token de solo lectura para los pull requests desde forks y de lectura y escritura para las ramas de confianza, de modo que un PR no fiable no pueda contaminar la caché.
Confirme los aciertos en el log. Una tarea en caché imprime [local cache] o [remote cache] y reproduce la salida en lugar de ejecutar el comando. Un resumen al final indica cuántas tareas se leyeron de la caché.
Sin Nx Cloud, puede usar otras implementaciones de caché remota mediante los plugins de caché y task runner personalizados de Nx, o almacenar en caché el directorio .nx/cache con actions/cache. La versión con la caché de Actions es la más económica para probar, con dos límites: las cachés de PR tienen un alcance acotado, y se aplica el tope de 10 GB del repositorio. Consulte límites de caché.
- uses: actions/cache@v6
with:
path: .nx/cache
key: nx-${{ runner.os }}-${{ github.sha }}
restore-keys: |
nx-${{ runner.os }}-
Paso 3: distribuya las tareas
Tras usar affected y la caché, un PR grande aún puede ser lento. Nx puede distribuir las tareas entre agentes. La introducción a CI de Nx (consultada en octubre de 2026) lo configura en .nx/ci-config.yaml e inicia los agentes en el workflow antes de la instalación:
# .nx/ci-config.yaml
dte:
distribute-on: 3 linux-large-js
lifecycle:
stop-after:
- build
steps:
- uses: actions/checkout@v6
with:
fetch-depth: 0
filter: tree:0
- run: npx nx-cloud start-workers
- uses: actions/setup-node@v7
with:
node-version: 22
cache: npm
- run: npm ci
- uses: nrwl/nx-set-shas@v5
- run: npx nx affected -t lint test build
Iniciar primero los workers les permite arrancar mientras su job principal instala las dependencias. Solo las tareas ejecutadas a través de nx se almacenan en caché y se distribuyen, así que asegúrese de que npm test envuelve a nx test en lugar de llamar directamente al ejecutor de pruebas.
Si prefiere quedarse con GitHub Actions puro, puede fragmentar usted mismo con una matriz. Nx admite dividir por proyecto y, para suites de pruebas grandes individuales, puede fragmentar el propio runner. Consulte fragmentación de pruebas en GitHub Actions.
Juntándolo todo
name: CI
on:
push:
branches: [main]
pull_request:
permissions:
actions: read
contents: read
jobs:
main:
runs-on: [self-hosted, Linux, compiler-ci] # or ubuntu-latest
steps:
- uses: actions/checkout@v6
with:
fetch-depth: 0
filter: tree:0
- uses: actions/setup-node@v7
with:
node-version: 22
cache: npm
- run: npm ci
- uses: nrwl/nx-set-shas@v5
- run: npx nx affected -t lint test build --parallel=4
--parallel controla cuántas tareas se ejecutan a la vez en la misma máquina. Con más núcleos, puede aumentar este valor. La línea runs-on es la única parte específica de compiler.dev: traslada el job a una máquina de 8 vCPU a $0.008 por minuto, y puede revertirlo cambiándola de nuevo. Consulte precios.
Errores que convierten affected en todo
- Checkout superficial. El más común. Use
fetch-depth: 0. - Modificar un archivo de la raíz. Cambiar
package-lock.json,nx.jsono un tsconfig compartido hace que todo quede afectado. LosnamedInputsde Nx le permiten acotar de qué depende cada target. - La base es un commit fallido. Usar
HEAD~1tras una ejecución fallida oculta los errores. nx-set-shas elige el último commit correcto. - Scripts que no son de Nx. Las tareas fuera de
nxomiten la lógica de caché y de affected. - Una caché que nunca se guarda. Asegúrese de que una rama de confianza la escriba.
Para instalaciones lentas, consulte caché de npm o caché de pnpm. Para otras herramientas de monorepo, consulte Turborepo y Bazel.
Preguntas frecuentes
¿Qué compara realmente nx affected?
Los archivos modificados entre NX_BASE y NX_HEAD, asignados a proyectos y a sus dependientes a través del grafo de proyectos.
¿Necesito Nx Cloud?
No para las ejecuciones de affected. Necesita una caché remota o una ejecución distribuida para reutilizar resultados entre ejecuciones; Nx Cloud es la vía compatible, y actions/cache sobre .nx/cache es una alternativa limitada.
¿Por qué nx affected ejecuta todo en mi PR?
Revise la profundidad del fetch, compruebe que NX_BASE no sea un ancestro inesperado de NX_HEAD, y mire si cambió algún archivo de configuración de la raíz.
¿Funciona esto con una merge queue?
nx-set-shas tiene una entrada use-previous-merge-group-commit (por defecto true) para los merge groups. Consulte merge queue de GitHub.
Relacionado
- Acelere un monorepo de TypeScript en GitHub ActionsAcelere la comprobación de tipos y el linting en un monorepo TypeScript con GitHub Actions: tsc incremental, referencias de proyecto y cachés.
- Acelere Playwright en un monorepo con GitHub ActionsAcelere las pruebas e2e de Playwright en un monorepo Node con GitHub Actions: compile la app una vez y omita e2e si no cambió.
- CI más rápido para monorepos de Bazel en GitHub ActionsCI rápido con Bazel en GitHub Actions: detección de objetivos, caché remota, subidas de solo lectura en PR, sharding y flujo completo.
- CI más rápido para workspaces de pnpm en GitHub ActionsCI rápido para espacios de trabajo pnpm en GitHub Actions. Filtros por paquetes modificados, caché del store, fetch-depth y matrix sharding.