Cachear compilaciones de Gradle en GitHub Actions
Última actualización
Para cachear Gradle en GitHub Actions, use gradle/actions/setup-gradle. Cachea el Gradle User Home (dependencias, wrapper, caché de compilación) y gestiona por usted las claves, la limpieza y el comportamiento de solo lectura. Una actions/cache escrita a mano para ~/.gradle/caches funciona, pero no cubre la mayor parte de eso.
Opción 1: setup-gradle
jobs:
build:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v6
- uses: actions/setup-java@v5
with:
distribution: temurin
java-version: 21
- uses: gradle/actions/setup-gradle@v6
- run: ./gradlew build
Esa es la configuración completa. Ejecute Gradle con el wrapper (./gradlew) después de la acción, porque la caché de la acción se guarda al terminar el job. No necesita actions/cache ni una key.
Lo que cachea la acción, según la documentación de setup-gradle (consultada en octubre de 2026): por defecto usa una caché mejorada de los subdirectorios caches del Gradle User Home, incluidas las dependencias descargadas (modules-2), las transformaciones, los jars generados, la caché de scripts del DSL de Kotlin y la caché de compilación local, además de las distribuciones del wrapper. Un modo básico cachea solo ~/.gradle/caches y ~/.gradle/wrapper.
Solo lectura en las ramas, escritura en main
Por defecto, solo los jobs de la rama predeterminada escriben en la caché. Los jobs de otras ramas leen lo que ya existe y no guardan. Así se evita que las pull requests llenen su cuota de 10 GB con entradas casi duplicadas, y significa que main debe ejecutar una compilación de Gradle para poblar la caché.
- uses: gradle/actions/setup-gradle@v6
with:
cache-read-only: ${{ github.ref != 'refs/heads/main' }}
Esa expresión es el comportamiento por defecto, mostrada para que pueda cambiarla. Por ejemplo, haga que una rama de release también escriba. La documentación describe cómo sobrescribirlo con cache-read-only, incluidas las expresiones de rama.
Limpieza
cache-cleanup elimina de Gradle User Home los archivos no utilizados antes de guardar la caché. Los valores son on-success (el predeterminado), always y never. Nunca se ejecuta cuando la caché es de solo lectura o está desactivada. Mantenga el valor predeterminado: sin él, la caché acumula todas las versiones de todas las dependencias que su proyecto haya usado alguna vez.
Cifrado de la caché de configuración
Si usa la caché de configuración de Gradle, las entradas pueden contener secretos. setup-gradle acepta una cache-encryption-key (una clave AES en base64, que puede generar con openssl rand -base64 16 y guardar como secreto) para que las entradas se cifren en la caché de GitHub.
Opción 2: actions/cache explícito
- uses: actions/cache@v6
with:
path: |
~/.gradle/caches
~/.gradle/wrapper
key: gradle-${{ runner.os }}-${{ hashFiles('**/*.gradle*', '**/gradle-wrapper.properties', '**/libs.versions.toml') }}
restore-keys: |
gradle-${{ runner.os }}-
Úselo si necesita evitar acciones alojadas por terceros, aunque gradle/actions lo mantiene el proyecto Gradle. Pierde la limpieza automática, el modo de solo lectura según la rama y las claves por job. Sin limpieza, las restore-keys siguen apilando nuevas entradas sobre las antiguas, y la caché crece hasta que se desaloja.
La caché de compilación de Gradle y la caché remota
Hay dos cachés en juego:
- Caché de dependencias (
modules-2): jars descargados. Ambas opciones anteriores la gestionan. - Caché de compilación: salidas de tareas, reutilizadas cuando las entradas coinciden. Actívela con
org.gradle.caching=trueengradle.propertieso con--build-cache. setup-gradle almacena la caché de compilación local dentro de la caché de GitHub, así que una PR puede reutilizar salidas de compilación y de tests demain.
En equipos más grandes, un nodo de caché de compilación remota (Develocity o un build-cache-node autoalojado) se comparte entre jobs y desarrolladores y no está limitado por los 10 GB de GitHub. Consulte la documentación de caché de compilación de Gradle para la configuración.
Añada también org.gradle.parallel=true y revise org.gradle.workers.max. Gradle usa por defecto el número de núcleos de CPU, así que una máquina más grande ayuda sin cambiar ninguna configuración. En el benchmark medido por compiler.dev, una ejecución de CI con Angular, Spring Boot (Gradle) y Postgres pasó de 6m57s en runners alojados por GitHub a 2m18s (vea benchmarks).
Qué cachear y qué no
| Ruta | ¿Cachear? | Notas |
|---|---|---|
~/.gradle/caches | Sí | Dependencias y caché de compilación |
~/.gradle/wrapper | Sí | La distribución de Gradle; evita una descarga en cada ejecución |
.gradle/ en el proyecto | Con cuidado | Contiene datos de la caché de configuración; setup-gradle lo gestiona |
Directorios build/ | No | Use la caché de compilación; las salidas incluyen rutas absolutas |
~/.m2 | Por separado | Solo si publica en o lee de Maven local |
Cómo verificar un acierto de caché
- El resumen del paso de setup-gradle en la página del job muestra las entradas de caché restauradas y guardadas, y sus tamaños.
- En la salida de Gradle,
FROM-CACHEjunto a una tarea significa que su salida procede de la caché de compilación.UP-TO-DATEsignifica sin cambios en local. - Las descargas de dependencias no deberían aparecer en la salida de
--infoen una ejecución en caliente. gh cache list --key gradle --limit 20muestra las entradas y su último uso.
Errores comunes
- No se llena la caché en main. Con ramas de solo lectura, no se guarda nada hasta que se ejecuta una compilación en la rama predeterminada.
- Ejecutar Gradle antes de la acción de setup. Coloque siempre la acción primero.
- Generar la clave manual con muy poco hash. Incluya los catálogos de versiones y las propiedades del wrapper.
- Almacenar en caché
build/. Es muy grande y no coincide entre commits. - Ignorar el tamaño. Las compilaciones de Android y de múltiples módulos generan cachés de varios GB. Consulte los límites de caché.
Preguntas frecuentes
¿Sigo necesitando actions/cache con setup-gradle?
No. setup-gradle lo reemplaza para Gradle User Home. Mantenga actions/cache para otros casos, como Node o Docker.
¿Funciona con Maven?
setup-gradle solo es compatible con Gradle. Para Maven, guarde en caché ~/.m2/repository con actions/setup-java y cache: maven, o use actions/cache con la clave **/pom.xml.
¿Por qué mi primera compilación de PR es lenta aunque use caché?
Si main aún no ha llenado la caché, o si la caché se ha eliminado, la PR empieza en frío. Ejecute una compilación en main.
¿Puedo usar el daemon de Gradle en CI?
Cada job nuevo inicia un daemon nuevo de todos modos. setup-gradle establece valores predeterminados razonables; rara vez necesitará cambiarlos.
Próximos pasos
Relacionado: cómo acelerar las compilaciones de Gradle de principio a fin, la caché de capas de Docker si su compilación de Gradle genera imágenes, y cómo acelerar GitHub Actions. Consulte los precios de compiler.dev para probar la misma compilación en una máquina de 8 vCPU.
Relacionado
- Cachear Cargo y compilaciones de Rust en GitHub ActionsCachee el registro de Cargo, las dependencias git y el directorio target en GitHub Actions con Swatinem/rust-cache o actions/cache, sin cachés inflados.
- Caché de módulos Go y de compilación en GitHub ActionsCachee los módulos Go (GOMODCACHE) y la caché de compilación (GOCACHE) en GitHub Actions con setup-go o actions/cache. Claves, go.sum y aciertos.
- Cachear dependencias de npm en GitHub ActionsAlmacene en caché las dependencias de npm en GitHub Actions con setup-node o actions/cache. YAML funcional, la clave correcta y por qué no node_modules.
- Caché de dependencias de pip en GitHub ActionsCachee pip en GitHub Actions con setup-python o actions/cache, además de la opción más rápida uv. Claves, qué no cachear y cómo verificar un acierto.