Saltar al contenido

CI de monorepos con Nx o Turborepo: compilaciones afectadas

Última actualización

En un monorepo, un cambio de una sola línea no debería reconstruir ni volver a probar todo. Dos ideas hacen posible esto: ejecutar tareas solo para los proyectos afectados por el cambio y reutilizar resultados de ejecuciones anteriores mediante una caché. Nx y Turborepo ofrecen ambas. Esta guía muestra la configuración de GitHub Actions para cada una y los errores que, sin avisar, convierten las compilaciones parciales otra vez en compilaciones completas.

Los tres niveles de "solo lo que cambió"

  1. Disparadores de workflows. Los filtros paths deciden si un workflow se inicia o no.
  2. Detección de proyectos afectados. La herramienta compara el cambio con un commit base y con el grafo de proyectos, y selecciona los proyectos que dependen de los archivos modificados.
  3. Caché de tareas. Para las tareas seleccionadas, la herramienta calcula un hash de las entradas y reutiliza los resultados si ya los ha visto. La caché remota comparte esos resultados entre las ejecuciones de CI y los desarrolladores.

Utilice los tres. Cada uno cubre un caso distinto.

Obtenga bien el commit base

La detección de proyectos afectados necesita historial. La acción actions/checkout predeterminada descarga un único commit, lo que no deja nada con qué comparar la herramienta. Descargue el historial completo o el suficiente:

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

El historial completo es sencillo y suficiente para la mayoría de los repositorios. En repositorios muy grandes, una descarga superficial más profunda (por ejemplo, fetch-depth: 50) funciona siempre que el merge base esté dentro de ella.

En los pull requests, compare con la rama de destino (origin/main). En los push a main, compare con el último commit exitoso anterior, no con el commit previo, para que una ejecución fallida no oculte cambios. Nx incluye una acción para esto:

- uses: nrwl/nx-set-shas@v4

Establece NX_BASE y NX_HEAD con la última ejecución exitosa en la rama principal y el commit actual.

Configuración de Nx

name: ci
on:
  pull_request:
  push:
    branches: [main]
jobs:
  main:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
      - uses: nrwl/nx-set-shas@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 22
          cache: npm
      - run: npm ci
      - run: npx nx affected -t lint test build

nx affected -t lint test build ejecuta esos objetivos solo para los proyectos afectados, en orden de dependencias, con caché local. Lee NX_BASE y NX_HEAD. Añada --parallel=3 para controlar la concurrencia en un runner pequeño. Para reutilizar resultados entre ejecuciones, conecte Nx Cloud u otra caché remota; sin ella, cada ejecución de CI empieza con una caché local vacía.

Configuración de Turborepo

La sintaxis de filtros de Turborepo selecciona por cambios en git:

- run: npx turbo run lint test build --filter="...[origin/main]"
  env:
    TURBO_TOKEN: ${{ secrets.TURBO_TOKEN }}
    TURBO_TEAM: ${{ vars.TURBO_TEAM }}

...[origin/main] significa "paquetes modificados desde origin/main, más todo lo que dependa de ellos". Con TURBO_TOKEN y TURBO_TEAM definidos, Turborepo usa una caché remota (la de Vercel o un servidor propio que implemente su API). Sin caché remota, puede conservar el directorio local .turbo con actions/cache, usando una clave deslizante. Consulte la guía de caché.

Defina con precisión las entradas y salidas de las tareas en turbo.json. Si inputs es demasiado amplio (por ejemplo, incluye un archivo que cambia en cada commit), las tareas nunca aciertan en la caché; si outputs omite una carpeta, las tareas reproducidas producirán resultados incompletos.

Caché remota: qué obtiene

Un acierto de caché omite el trabajo por completo y reproduce los registros y archivos. En un PR típico que modifica un paquete, se recompilan los paquetes que dependen de él y todo lo demás es un acierto. Los efectos son mayores cuando:

  • Varios PR modifican las mismas rutas de código, así que los resultados se comparten.
  • Los desarrolladores y la CI comparten caché, de modo que la CI reproduce lo que compiló un portátil.
  • Las tareas son deterministas. Las tareas que leen el reloj, la red o semillas aleatorias no pueden almacenarse en caché de forma segura.

Trate las credenciales de la caché remota como secretos y restrinja el acceso de escritura a las ramas de confianza. Una caché envenenada es un riesgo para la cadena de suministro, así que no permita que los pull requests desde forks escriban en ella. Consulte cómo proteger GitHub Actions.

Filtros de disparo adicionales

Un filtrado sencillo a nivel de workflow ayuda cuando partes del repositorio no están relacionadas, como un sitio de documentación o código de infraestructura:

on:
  pull_request:
    paths:
      - "apps/**"
      - "packages/**"
      - "package-lock.json"
      - ".github/workflows/ci.yml"

Incluya el propio archivo del workflow y los archivos de bloqueo. Si el workflow es un check obligatorio, una ejecución omitida deja el check en "Expected" para siempre; resuélvalo con un job de resumen que siempre se ejecute o con la detección de rutas dentro del workflow.

Errores frecuentes

  • El clon superficial hace que el conjunto afectado esté vacío o incluya todo, según la herramienta.
  • Los archivos globales, como el package.json raíz, el archivo de bloqueo o el tsconfig, cambian el hash de todos los proyectos. Es correcto, pero asegúrese de que los archivos no relacionados no figuren como entradas globales.
  • Las dependencias implícitas, por ejemplo, un servicio que lee un archivo de esquema de otro paquete sin declarar la dependencia. La detección de afectados no las detecta. Declárelas en la configuración del proyecto.
  • Los despliegues no deberían depender de compilaciones solo de los afectados sin una red de seguridad de compilación completa en main o de forma nocturna.
  • Tamaño de la caché: una caché remota crece sin límite a menos que establezca un periodo de retención.

Mida el beneficio

Registre la mediana y el percentil 90 del tiempo de CI de los PR antes y después. Registre también la fracción de tareas servidas desde caché. Si después de una semana se mantiene por debajo de aproximadamente la mitad, revise la configuración de entradas y del commit base. Use el estimador de minutos de CI para convertir los minutos ahorrados en una cifra mensual, y el planificador de sharding de tests si los proyectos afectados siguen ejecutando suites largas.

Preguntas frecuentes

¿Nx o Turborepo?

Ambos ofrecen ejecuciones de afectados y caché. Nx tiene un grafo de proyectos más completo, generadores y ejecución distribuida de tareas; Turborepo es más ligero y más sencillo de añadir a un workspace de npm existente. Elija según lo que necesite más allá de la caché.

¿Sigo necesitando filtros de rutas?

Sí, para los casos sencillos: evitan iniciar un runner. Las herramientas se encargan después de las decisiones más finas.

¿Funciona esto en repositorios que no son de JavaScript?

Nx tiene plugins para varios lenguajes, y herramientas como Bazel, Pants y Gradle tienen su propia lógica de caché y de afectados. Los principios (commit base, grafo y caché) son los mismos.

¿Por qué todo se marca como afectado en cada PR?

Normalmente se debe a un archivo global modificado, a un checkout superficial o a un SHA base incorrecto. Muestre la lista de proyectos afectados con nx show projects --affected para depurarlo.

Dónde encaja compiler.dev

Las compilaciones afectadas reducen el número de jobs que se ejecutan; los runners más rápidos reducen el tiempo que tarda cada uno. El modo de comparación de compiler.dev ejecuta su workflow existente en máquinas más rápidas para que pueda medir este segundo efecto en su propio repositorio.

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

Pruébelo gratis