Saltar al contenido

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=true en gradle.properties o 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 de main.

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/cachesSíDependencias y caché de compilación
~/.gradle/wrapperSíLa distribución de Gradle; evita una descarga en cada ejecución
.gradle/ en el proyectoCon cuidadoContiene datos de la caché de configuración; setup-gradle lo gestiona
Directorios build/NoUse la caché de compilación; las salidas incluyen rutas absolutas
~/.m2Por separadoSolo si publica en o lee de Maven local

Cómo verificar un acierto de caché

  1. 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.
  2. En la salida de Gradle, FROM-CACHE junto a una tarea significa que su salida procede de la caché de compilación. UP-TO-DATE significa sin cambios en local.
  3. Las descargas de dependencias no deberían aparecer en la salida de --info en una ejecución en caliente.
  4. gh cache list --key gradle --limit 20 muestra las entradas y su último uso.

Errores comunes

  1. 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.
  2. Ejecutar Gradle antes de la acción de setup. Coloque siempre la acción primero.
  3. Generar la clave manual con muy poco hash. Incluya los catálogos de versiones y las propiedades del wrapper.
  4. Almacenar en caché build/. Es muy grande y no coincide entre commits.
  5. 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.

Ejecute esta compilación de Gradle en compiler.dev Sin tarjeta · 200 minutos gratuitos

Pruébelo gratis