CI más rápido para monorepos de Turborepo en GitHub Actions
Última actualización
Un CI rápido para Turborepo se consigue con dos cosas: ejecutar solo los paquetes que han cambiado y reutilizar la salida de las tareas almacenada en una caché remota. Turborepo ofrece --filter para lo primero y una Remote Cache para lo segundo. Esta guía explica cómo integrar ambas en GitHub Actions y qué configuración de git determina si funcionan. Para la comparativa con Nx, consulte la descripción general de Nx y Turborepo.
Paso 1: ejecutar solo los paquetes modificados
turbo run build test lint --filter="...[origin/main]"
La parte [origin/main] selecciona los paquetes con cambios desde origin/main. El ... inicial añade también todo lo que depende de ellos, que es lo que se necesita en CI: un cambio en una biblioteca compartida debe volver a probar a sus consumidores. Sin ... solo se obtienen los paquetes cuyos propios archivos han cambiado.
pnpm utiliza la misma sintaxis de selección; consulte workspaces de pnpm. Las versiones recientes de Turborepo también tienen un flag --affected que elige una base automáticamente; consulte la documentación de Turborepo para la versión instalada.
Profundidad de fetch
Un filtro contra origin/main necesita esa referencia y suficiente historial para encontrar el merge base. actions/checkout descarga por defecto un solo commit, así que use una de estas opciones:
- uses: actions/checkout@v6
with:
fetch-depth: 0 # full history: safest
La guía de Turborepo para GitHub Actions (revisada en octubre de 2026) usa fetch-depth: 2 en sus ejemplos, lo cual basta para comparar con el commit anterior en main, pero no para una rama de PR de larga duración comparada con origin/main. Para los PR, lo más seguro es el historial completo o filter: tree:0 con fetch-depth: 0. En los push a main es habitual comparar con el commit anterior:
- run: turbo run build test --filter="...[HEAD^1]"
En los pull requests puede comparar dinámicamente con la rama base:
- run: turbo run build test --filter="...[origin/${{ github.base_ref }}]"
if: github.event_name == 'pull_request'
Paso 2: Remote Cache
La caché local de Turborepo se guarda en node_modules/.cache/turbo, que desaparece con cada runner nuevo. Una Remote Cache almacena las salidas por hash, de modo que otro runner, otra rama u otro miembro del equipo obtiene el mismo resultado sin ejecutar la tarea.
La documentación de Turborepo describe dos formas de autenticarse en GitHub Actions. Con un token, defina TURBO_TOKEN como secreto y TURBO_TEAM como variable:
jobs:
build:
runs-on: ubuntu-latest
env:
TURBO_TOKEN: ${{ secrets.TURBO_TOKEN }}
TURBO_TEAM: ${{ vars.TURBO_TEAM }}
Su guía también describe una configuración con OIDC que usa vercel/setup-turborepo-remote-cache-action, que requiere el permiso id-token: write e intercambia un token de GitHub de corta duración por un token de caché. Debe ejecutarse antes de cualquier paso que llame a turbo. Prefiera OIDC cuando sea posible; no hay ningún secreto de larga duración que pueda filtrarse.
Un acierto de caché aparece en la salida como cache hit, replaying logs con un hash, y la línea de resumen muestra Cached: N cached, M total. Una ejecución totalmente cacheada muestra FULL TURBO.
Si no quiere una caché alojada, puede ejecutar un servidor de caché autoalojado que implemente la API de caché remota de Turborepo, o recurrir a actions/cache sobre .turbo:
- uses: actions/cache@v6
with:
path: .turbo
key: turbo-${{ runner.os }}-${{ github.sha }}
restore-keys: |
turbo-${{ runner.os }}-
Este es el patrón de caché rodante descrito en Caché en GitHub Actions. Funciona si apunta el directorio de caché de Turborepo a .turbo. Está limitado por el tope de 10 GB y por el alcance de las ramas; consulte límites de caché.
Paso 3: sharding y paralelismo
Turborepo ejecuta tareas en paralelo en una misma máquina, limitado por --concurrency (por defecto 10). No distribuye las tareas entre varias máquinas por sí mismo. Sus opciones son:
- Más núcleos. A menudo es lo más económico.
--concurrencypuede aumentarse en runners más grandes. - Matriz por tarea. Ejecute lint, test y build como trabajos separados que usen la caché remota, de modo que el trabajo ya hecho por un trabajo se reutilice en otro.
- Matriz por grupo de paquetes. Use
--filterpor aplicación. Combínelo con sharding de tests para suites de pruebas grandes.
strategy:
fail-fast: false
matrix:
task: [lint, test, build]
steps:
- run: turbo run ${{ matrix.task }} --filter="...[origin/main]"
Cada trabajo de la matriz asume el coste de checkout e instalación, así que cachee bien las dependencias; consulte caché de pnpm y caché de npm.
Un workflow completo
name: CI
on:
push:
branches: [main]
pull_request:
jobs:
ci:
runs-on: [self-hosted, Linux, compiler-ci] # or ubuntu-latest
timeout-minutes: 20
env:
TURBO_TOKEN: ${{ secrets.TURBO_TOKEN }}
TURBO_TEAM: ${{ vars.TURBO_TEAM }}
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: Run changed packages
run: pnpm turbo run lint test build --filter="...[origin/${{ github.base_ref || 'main' }}]"
En un push, github.base_ref está vacío, por lo que la expresión recurre a main. En el propio main eso compara main con main y no selecciona nada, así que en los push use --filter="...[HEAD^1]" o ejecute todo y deje que la caché reutilice los resultados.
En compiler.dev, la línea runs-on le proporciona una máquina de 8 vCPU a $0.008 por minuto con las cachés de dependencias ya preparadas, y puede revertirla cambiando la línea de nuevo. En una ejecución medida de un proyecto con Turborepo, Next.js, tRPC y MySQL, el CI pasó de 3m29s en runners alojados por GitHub a 1m53s (consulte benchmarks).
Errores que anulan el filtrado
- Clon superficial. Si falta el merge base, Turborepo considera que muchos paquetes han cambiado.
- Entradas de clave de caché demasiado amplias. Los archivos fuera del paquete que se incluyen en el hash de una tarea (dependencias globales en
turbo.json) invalidan todo cuando cambian. - Variables de entorno no declaradas. Si una tarea lee una variable de entorno que no está en
envni englobalEnv, las entradas de caché pueden compartirse incorrectamente o fallar sin motivo. - Distinto
TURBO_TEAMentre trabajos. Los trabajos usarán entonces cachés diferentes. - PR no confiables escribiendo en la caché. Limite el acceso de escritura a ramas de confianza.
Preguntas frecuentes
¿Qué significa ...[origin/main] en turbo --filter?
Los paquetes cambiados desde origin/main, más sus dependientes gracias al ... inicial.
¿Necesito Vercel para la Remote Cache?
La opción alojada documentada es la de Vercel. También puede ejecutar un servidor de caché autoalojado compatible.
¿Por qué el CI reconstruye todo en main?
En los push no hay base de PR. Compare con el commit anterior o con el último que pasó correctamente, o confíe en la caché remota para reutilizar resultados.
¿Turborepo distribuye las tareas entre varias máquinas?
No por sí mismo. Use una matriz o runners más grandes, como se ha descrito anteriormente.
Relacionado
- 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 monorepos de Nx en GitHub ActionsHaga rápido su CI de Nx en GitHub Actions: nx affected con nx-set-shas, caché remota de Nx, distribución de tareas 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.
- CI de monorepos con Nx o Turborepo: compilaciones afectadasEjecute solo lo modificado en un monorepo con GitHub Actions. Nx affected, filtros de Turborepo, caché remota, path filters y la configuración de checkout.