Cachear en CI: dependencias y caché remota de tareas

El runner de CI tiene una propiedad incómoda: es efímero. Nace con el disco en blanco en cada corrida, sin node_modules, sin store de paquetes, sin artefactos de la vez anterior. Sin cachés, eso significa descargar todas las dependencias y recomputar todos los builds y tests desde cero en cada empujón, aunque el cambio fuera de una línea. La solución son dos cachés que atacan dos desperdicios distintos y que no conviene confundir: la caché de dependencias evita volver a descargar lo que ya se descargó, y la caché remota de tareas evita volver a ejecutar lo que ya se ejecutó. La primera se indexa por el lockfile; la segunda, por el hash del contenido de las entradas de cada tarea. Entender esa diferencia es lo que evita el error de esperar que una haga el trabajo de la otra.

Dos cachés que no hay que confundir

El error conceptual más caro en CI es tratar “cachear” como una sola cosa. Son dos, y atacan capas distintas del desperdicio. La caché de dependencias guarda lo que pnpm install descargó de la red: el store de paquetes. Su enemigo es el ancho de banda y el tiempo de resolución, y su clave natural es el lockfile, porque el lockfile determina por completo qué se instala. La caché de tareas guarda lo que build, test y lint produjeron: artefactos de salida y logs. Su enemigo es el cómputo, y su clave es el hash del contenido de todo lo que entra en la tarea —fuentes, configuración, dependencias—, no el lockfile.

flowchart TD
R[runner efimero arranca] --> DC[cache de deps por hash del lockfile]
DC -->|acierto| I[restaura el store sin descargar]
DC -->|fallo| N[pnpm install descarga y siembra]
I --> TC[cache remota de tareas por hash de inputs]
N --> TC
TC -->|acierto| RE[restaura build y test sin ejecutar]
TC -->|fallo| EX[ejecuta build test lint y sube]
style DC fill:#89b4fa,color:#11111b
style TC fill:#cba6f7,color:#11111b
style RE fill:#a6e3a1,color:#11111b

La confusión típica es esperar que la caché de dependencias acelere los builds, o que la de tareas evite instalar. No lo hacen: son ortogonales. Un runner puede acertar la caché de dependencias —no descarga nada— y aun así ejecutar todos los builds porque falló la de tareas; o al revés. El pipeline rápido las tiene las dos, encadenadas: primero restaura el store para no descargar, luego consulta la caché de tareas para no computar, y solo hace trabajo real en lo que ninguna de las dos cubrió.

La caché de dependencias de pnpm

pnpm tiene una arquitectura que la hace ideal para cachear: no copia paquetes dentro de cada node_modules, sino que mantiene un store global direccionado por contenido y enlaza desde él con enlaces duros. Cachear ese store, y no los node_modules, es lo correcto: el store es estable, compartido entre proyectos y se restaura rápido. La forma más limpia en GitHub Actions es delegar en setup-node, que conoce pnpm y calcula la clave a partir del lockfile por ti.

- uses: pnpm/action-setup@v4
- uses: actions/setup-node@v4
  with:
    node-version: 22
    cache: pnpm
- run: pnpm install --frozen-lockfile

La clave de esta caché es un hash de pnpm-lock.yaml. La consecuencia es exacta y deseable: mientras el lockfile no cambie, el store se restaura tal cual; en cuanto añades o subes una dependencia, el lockfile cambia, la clave cambia y la caché se rehace. Esto es justo lo que quieres, porque el lockfile es la definición precisa de qué debe haber en el store. Y --frozen-lockfile cierra el círculo: obliga a que la instalación respete el lockfile al pie de la letra y falle si no cuadra, de modo que CI nunca resuelve versiones por su cuenta ni introduce una deriva que la caché luego perpetuaría.

La caché remota de tareas: Turborepo y Nx

La caché de dependencias resuelve la descarga, pero el cómputo —construir, testear, lintar— sigue ocurriendo de cero en cada runner efímero, porque su disco nace vacío y la caché de tareas local no viaja con él. La respuesta es una caché remota: un almacén compartido, indexado por el hash del contenido de las entradas de cada tarea, del que cualquier máquina puede bajar un resultado que otra ya computó. En Turborepo se activa con dos variables de entorno, porque el runner no puede hacer un login interactivo.

    env:
      TURBO_TOKEN: ${{ secrets.TURBO_TOKEN }}
      TURBO_TEAM: ${{ vars.TURBO_TEAM }}
    steps:
      - run: pnpm install --frozen-lockfile
      - run: pnpm turbo run build test lint

TURBO_TOKEN autentica al runner contra el almacén remoto y TURBO_TEAM identifica el ámbito cuya caché se comparte; el token vive en los secretos del repositorio y el equipo en una variable normal, porque no es secreto. Con esas dos presentes, cada turbo run consulta el almacén antes de ejecutar: si otro runner, o el portátil de un compañero, ya subió el artefacto para ese hash, lo descarga y reproduce sus logs en milisegundos en lugar de recomputar. Nx tiene el equivalente con Nx Cloud, donde nx connect enlaza el workspace y la misma idea de acierto remoto por hash aplica. En ambos, el runner efímero deja de nacer con la caché fría: aunque su disco esté vacío, pregunta a la red si el trabajo ya existe.

Diseñar la clave: ni floja ni imposible

Toda caché vive o muere por su clave, y hay dos formas simétricas de arruinarla. Una clave demasiado floja —que ignora algo que sí afecta al resultado— sirve resultados obsoletos: acierta cuando no debería y restaura un artefacto que ya no corresponde a las entradas. Una clave demasiado apretada —que incluye algo irrelevante y volátil, como una marca de tiempo o el nombre del runner— no acierta nunca: cada corrida produce una clave nueva y la caché se convierte en almacenamiento inútil que solo escribes y jamás lees.

El caso “acierta en mi máquina pero falla en CI” merece un nombre propio, porque es el más frecuente y su causa nunca es la red. Es que el hash difiere entre los dos entornos, y difiere porque alguna entrada no está declarada: una variable de entorno presente en tu shell y ausente en el runner, un archivo generado localmente que se cuela en las entradas, una versión de herramienta distinta. Comparar el hash de una corrida en seco en ambos entornos localiza la fuga en minutos.

turbo run build --dry=json    # el plan y los hashes, sin ejecutar
turbo run build --summarize   # cuantas tareas acertaron y cuantas corrieron

Este trabajo de afinar la clave es, en el fondo, un trabajo de empujar tus tareas hacia el determinismo. Una tarea cuya salida depende solo de sus entradas declaradas es memoizable con seguridad; una que incrusta la hora, un identificador aleatorio o el nombre de la máquina rompe la promesa de que un mismo hash implica un mismo resultado, y con ella la legitimidad de toda la caché. Buena parte de configurar bien el cacheado en CI no es tocar la caché, sino purgar el no-determinismo de lo que cacheas.