Turborepo con Vercel Remote Cache: login, link y tokens en CI

La forma más rápida de pasar de la teoría a una caché compartida real es la caché alojada de Vercel, el destino por defecto de Turborepo y de cero infraestructura para ti. En tu máquina son dos comandos: turbo login autentica contra Vercel, y turbo link asocia el repositorio con la caché remota de un equipo. A partir de ahí, cada turbo run sube y baja artefactos solo. En CI, donde no hay navegador ni login interactivo, el mismo enlace se establece con dos variables de entorno, TURBO_TOKEN y TURBO_TEAM. Gratis para uso personal, de pago para equipos.

En tu máquina: login y link

La caché remota de Vercel es la opción de configuración cero: no hay servidor que levantar ni almacenamiento que aprovisionar. Se activa con dos comandos. El primero autentica tu CLI contra tu cuenta de Vercel; abre el navegador, completas el flujo, y queda un token guardado localmente.

turbo login
turbo link

El segundo, turbo link, asocia este repositorio con la caché remota de un ámbito concreto —tu cuenta personal o un equipo—. Escribe un .turbo/config.json con el identificador del equipo y el endpoint de la API; ese archivo no contiene secretos y puede comitearse sin problema. Desde ese momento, cualquier turbo run build consulta la caché remota antes de compilar: si otra máquina ya subió el artefacto para ese hash, lo descarga y reproduce; si no, compila y lo sube para quien venga después. La primera corrida siembra la caché; todas las siguientes, tuyas o de tus compañeros, la cosechan.

Merece la pena entender qué guarda turbo link y qué no. Escribe el identificador del equipo y el endpoint en .turbo/config.json —datos no sensibles, comiteables—, pero no guarda ahí el token: ese vive aparte, en la configuración global de tu usuario tras el turbo login. La separación es deliberada. La asociación entre el repositorio y el equipo es pública dentro de tu organización; la credencial que autoriza a leer y escribir en la caché es personal y no debe viajar jamás en el repositorio. Esa misma distinción entre “a qué equipo pertenezco” y “con qué permiso entro” reaparece, amplificada, en el momento de conectar CI.

Antes de seguir, conviene fijar qué cambia en tu día a día una vez enlazado: nada en tu forma de trabajar. Sigues ejecutando turbo run build igual que antes. Lo único distinto es que, por debajo, cada tarea consulta primero si su resultado ya existe en la caché compartida y solo compila si no. La caché remota es deliberadamente invisible cuando funciona; su presencia se nota únicamente en que las cosas tardan mucho menos de lo que deberían.

En CI: TURBO_TOKEN y TURBO_TEAM

CI no puede hacer turbo login: no hay navegador, no hay quien complete un flujo interactivo, y el runner es efímero. La conexión se establece, en cambio, por variables de entorno. TURBO_TOKEN es un token de acceso de Vercel que autentica al runner, y TURBO_TEAM es el identificador del equipo cuya caché se comparte. Con esas dos presentes, turbo se conecta a la caché remota sin ninguna interacción.

name: ci
on: push
jobs:
  build:
    runs-on: ubuntu-latest
    env:
      TURBO_TOKEN: ${{ secrets.TURBO_TOKEN }}
      TURBO_TEAM: ${{ vars.TURBO_TEAM }}
    steps:
      - uses: actions/checkout@v4
      - uses: pnpm/action-setup@v4
      - run: pnpm install --frozen-lockfile
      - run: pnpm turbo run build test lint

El token va en los secretos del repositorio, nunca en el YAML ni en el control de versiones; el equipo puede ir en una variable normal porque no es secreto. Con esto, el runner efímero del nivel uno deja de nacer con la caché fría: aunque su disco esté vacío, ahora puede preguntarle a la caché remota si el trabajo ya existe, y para el noventa por ciento intacto la respuesta será que sí.

El token merece el mismo cuidado que cualquier credencial de producción, porque en la práctica lo es. Dale el alcance mínimo que necesite, guárdalo en el almacén de secretos de tu CI y no en el YAML, y rótalo con la cadencia con la que rotarías la llave de una base de datos. Un token de caché filtrado no es tan catastrófico como uno de despliegue, pero permite a un tercero leer los artefactos de tus builds y, peor, escribir en la caché que todo tu equipo consume.

Conviene conocer dos variables más que rondan este mismo mecanismo. TURBO_API apunta al endpoint de la caché, y su valor por defecto es el de Vercel; cambiarlo es lo que permite apuntar a una caché self-hosted, como veremos. Y TURBO_REMOTE_CACHE_SIGNATURE_KEY activa la firma de artefactos: si la defines con la misma clave en todas las máquinas, cada artefacto se firma al subir y se verifica al bajar, de modo que un artefacto manipulado se rechaza antes de restaurarse.

Blindar la caché compartida frente a PRs no confiables

Una caché remota es estado compartido y mutable, y todo estado compartido y mutable es una superficie de ataque. El escenario a temer es el PR desde un fork no confiable: si el pipeline de ese PR tiene un token de escritura, código malicioso en el PR podría subir un artefacto envenenado bajo el hash de una tarea legítima, y entonces cualquier máquina —CI de la rama principal incluida— que obtenga ese “acierto” restauraría la salida manipulada. Es una forma de cache poisoning, y no es hipotética: envenenamientos de caché de build documentados en 2025 mostraron exactamente esta clase de fallo.

La defensa es el mínimo privilegio sobre la caché. Para los contextos no confiables, el runner debe poder leer de la caché pero no escribir en ella. Turborepo permite ese modo de solo lectura, de forma que un PR de fork se beneficia de los aciertos existentes sin poder contaminar el almacén compartido.

# En jobs disparados por PRs de forks: leer si, escribir no
turbo run build --remote-cache-read-only

El principio que subyace es el de mínimo privilegio aplicado a un recurso compartido: cada consumidor de la caché recibe justo el acceso que su nivel de confianza justifica, y ni una pizca más. El CI de la rama principal, que corre código ya revisado y fusionado, puede escribir; el CI de un PR de un fork, que corre código de un desconocido, solo lee. Esta asimetría no es paranoia, sino el reconocimiento de que una caché compartida amplifica por igual el trabajo legítimo y el malicioso, y que la única frontera entre ambos es quién tiene permiso para escribir en ella.

Vale la pena nombrar por qué los forks son el caso peligroso y no los PRs internos. Un PR de un miembro del equipo corre código de alguien con acceso legítimo, cuya mala intención sería un problema mayor que la caché; un PR de un fork corre código de cualquier desconocido de internet que abrió un pull request. Darle a ese código permiso de escritura sobre la caché que tu producción consume es, literalmente, dejar que un extraño deposite artefactos que tu equipo restaurará. Solo lectura para forks no es paranoia, es la configuración correcta por defecto.

Verificar y depurar la caché

Activar la caché es fácil; confiar en ella exige saber inspeccionarla. La primera herramienta es la corrida en seco, que muestra el plan —qué tareas correrían, con qué hash, con qué entradas— sin ejecutar nada. Es lo primero que hay que mirar cuando un acierto que esperabas no aparece, porque casi siempre revela la causa: un hash que difiere entre dos entornos que deberían coincidir.

turbo run build --dry=json    # el plan y los hashes, sin ejecutar
turbo run build --summarize   # un resumen de la ejecucion real

El síntoma clásico de un problema es “en mi máquina acierta pero en CI no”. La causa nunca es la red: es que el hash difiere, y difiere porque alguna entrada no está declarada o cambia entre los dos entornos —una variable presente en tu shell y ausente en CI, un archivo generado localmente que se cuela en los inputs, una versión de dependencia distinta—. Comparar los hashes de la corrida en seco en ambos entornos localiza la fuga en minutos, no en horas.

# Tras un cambio pequeno con la cache caliente
 Tasks:    18 successful, 18 total
Cached:    17 cached, 18 total   # 17 aciertos, solo 1 tarea corrio
  Time:    3.4s

El resumen de una ejecución te da el número que lo condensa todo: cuántas tareas acertaron y cuántas corrieron. Cuando todas aciertan aparece FULL TURBO, la señal de que ni una sola tarea se ejecutó. Convertir ese número en una métrica que vigilas a lo largo del tiempo es lo que transforma la caché de una comodidad ocasional en una garantía de la que dependes.

Un último hábito de verificación que ahorra sustos: revisa de vez en cuando que la caché no se esté escribiendo desde donde no debe. Un vistazo a quién ha subido artefactos recientemente, o una comprobación de que los jobs de PR corren en solo lectura, detecta a tiempo tanto un token demasiado amplio como una configuración que, sin querer, dejó a un contexto no confiable con permiso de escritura. La caché compartida es infraestructura, y la infraestructura se audita.