Acelere Gradle en GitHub Actions
Última actualización
Para acelerar Gradle en GitHub Actions, use gradle/actions/setup-gradle para la caché, active la caché de compilación de Gradle, la caché de configuración y la ejecución en paralelo, y divida las pruebas en forks a través de los núcleos. Gradle es muy adecuado para la caché porque sabe qué salidas de tareas siguen siendo válidas, pero solo si le proporciona una caché que persista entre ejecuciones.
Esta guía muestra la configuración y un flujo de trabajo completo. Para el enfoque general, lea cómo acelerar GitHub Actions.
Use setup-gradle, no una caché propia
gradle/actions/setup-gradle es la acción oficial de Gradle. Según su documentación, la caché está activada de forma predeterminada con el proveedor enhanced, y conviene conocer algunos comportamientos:
- Solo los trabajos de la rama predeterminada escriben en la caché. Las demás ramas la leen. Así se protege la caché del ruido de los pull requests.
- Los daemons se detienen en el paso posterior, antes de guardar la caché.
- La caché solo se limpia cuando todas las compilaciones de Gradle del trabajo se completan correctamente.
cache-read-only: truehace que un trabajo solo lea, sin escribir, algo útil para trabajos que ejecutan tareas poco habituales.- Los datos de la caché de configuración pueden guardarse si establece
cache-encryption-key(una clave AES en base64, generada conopenssl rand -base64 16y almacenada como secreto).
- uses: actions/checkout@v7
- uses: actions/setup-java@v6
with:
distribution: temurin
java-version: 21
- uses: gradle/actions/setup-gradle@v6
- run: ./gradlew build --scan
setup-java tiene su propia opción cache: gradle. No active ambas; setup-gradle hace más y pueden entrar en conflicto.
gradle.properties para CI
Tres ajustes cambian el tiempo de compilación más que ningún otro. Colóquelos en gradle.properties (así las compilaciones locales también los usan) o páselos como indicadores:
org.gradle.caching=true
org.gradle.parallel=true
org.gradle.configuration-cache=true
org.gradle.jvmargs=-Xmx3g -XX:+UseParallelGC
- Caché de compilación (
org.gradle.caching) reutiliza las salidas de las tareas cuyas entradas no cambiaron, como las clases compiladas y los resultados de las pruebas. Consetup-gradlese almacena en la caché de GitHub Actions. En un acierto de caché, los módulos completos aparecen comoFROM-CACHE. - Paralelo (
org.gradle.parallel) ejecuta a la vez los subproyectos independientes. Ayuda en compilaciones multimódulo y no tiene efecto en un único módulo. - Caché de configuración (
org.gradle.configuration-cache) guarda el resultado de la fase de configuración, de modo que las compilaciones repetidas la omiten. Requiere plugins compatibles, y algunas compilaciones fallan con infracciones hasta corregirlas. Ejecute./gradlew build --configuration-cacheuna vez y revise el informe antes de activarla de forma permanente. La documentación de Gradle indica la compatibilidad de los plugins. - Memoria de la JVM. Un runner alojado por GitHub de 2 vCPU predeterminado tiene 7 GB de RAM, por lo que el tamaño del heap importa. Si es demasiado pequeño, Gradle pasa tiempo en la recolección de basura; si es demasiado grande, el runner usa swap.
Paralelismo de pruebas
Gradle ejecuta por defecto las clases de prueba en una sola JVM. Dos propiedades en build.gradle.kts aprovechan más núcleos:
tasks.withType<Test>().configureEach {
maxParallelForks = (Runtime.getRuntime().availableProcessors() / 2).coerceAtLeast(1)
forkEvery = 0
useJUnitPlatform()
}
maxParallelForks inicia ese número de JVM de prueba en paralelo para un módulo. Cada fork usa memoria y sus propias conexiones a la base de datos, así que las pruebas que comparten una base de datos necesitan aislamiento por fork (por ejemplo, un esquema o un contenedor por fork) o colisionarán. Con Testcontainers, los contenedores por fork multiplican el uso de memoria. Si en cambio reparte las pruebas entre trabajos, sirven el filtro --tests de Gradle o un plugin que divida por tiempos; consulte la división de pruebas en GitHub Actions.
Evite hacer el trabajo dos veces
buildejecuta todo. Si además ejecutatestycheckpor separado, vuelve a ejecutar tareas que ya estaban actualizadas. Gradle omite las tareas actualizadas dentro de una misma invocación, pero los pasos separados en una VM nueva no comparten salidas a menos que la caché de compilación esté activada.- Ejecute una vez y pase los artefactos. Compile en un trabajo con
./gradlew assembley ejecute las pruebas en varios trabajos que restauren desde la caché de compilación. - Omita lo que no necesita. Use
-x javadoco-x dokkaHtmlen las comprobaciones de PR, y genere la documentación solo en las publicaciones. - Wrapper. Use siempre
./gradlew, para fijar la distribución.setup-gradlealmacena en caché la distribución del wrapper descargada. - Docker. Si construye imágenes desde Gradle, la caché de capas importa más que la configuración de Gradle. Consulte la caché de capas de Docker en CI.
Lea el build scan
--scan (o el plugin Develocity) muestra las líneas de tiempo de las tareas, los motivos de aciertos y fallos de caché y la resolución lenta de dependencias. Si una tarea falla la caché en cada ejecución, el escaneo muestra qué entrada cambió. Las causas habituales son marcas de tiempo incrustadas en las salidas, rutas absolutas y versiones dinámicas sin fijar, como 1.+.
Lo que aportan más núcleos de CPU
Gradle paraleliza proyectos y pruebas, y el compilador de la JVM es multihilo, por lo que se beneficia más que la mayoría de los stacks. En nuestros benchmarks, un proyecto Angular + Spring Boot (Gradle) + Postgres pasó de 6m57s en un runner alojado por GitHub a 2m18s en compiler.dev (3.0x). Es nuestra mayor aceleración, medida en una ejecución completa de CI con 10 shards de pruebas y una base de datos real, el 8 de octubre de 2026. También dispuso de más memoria, 16 GB frente a 7 GB, lo que ayuda en las compilaciones de la JVM.
Los resultados varían según el grado de paralelismo del grafo de módulos. Un único módulo grande gana menos. Para medirlo, cambie una línea a runs-on: [self-hosted, Linux, compiler-ci]; consulte precios y comparar. Relacionado: la plantilla de Gradle, la guía de Maven y la caché de GitHub Actions.
Preguntas frecuentes
¿Debo usar setup-java cache: gradle o setup-gradle?
Use gradle/actions/setup-gradle. Almacena en caché más y gestiona el ciclo de vida de la caché. No active ambas.
¿Por qué solo la rama principal escribe la caché de Gradle?
Así evita que las compilaciones de PR llenen y desalojen la caché compartida. Las ramas siguen leyendo lo que guardó main. Puede cambiarlo con cache-read-only.
¿Es seguro activar la caché de configuración de Gradle?
Es estable en versiones recientes de Gradle, pero cada plugin debe ser compatible. Pruébela primero con --configuration-cache y corrija los problemas que se notifiquen.
¿Cuántos forks de pruebas en paralelo debo usar?
Empiece con la mitad de los núcleos y vigile la memoria. Las pruebas que usan una base de datos compartida necesitan aislamiento por cada fork.
Relacionado
- Acelere un monorepo de TypeScript en GitHub ActionsAcelere la comprobación de tipos y el linting en un monorepo TypeScript con GitHub Actions: tsc incremental, referencias de proyecto y cachés.
- Acelere Playwright en un monorepo con GitHub ActionsAcelere las pruebas e2e de Playwright en un monorepo Node con GitHub Actions: compile la app una vez y omita e2e si no cambió.
- Añada una insignia de velocidad de CI a su READMEMuestre la velocidad de su CI con una insignia en el README: el tiempo mediano de ejecución en GitHub Actions, actualizado automáticamente. Gratis.
- Cachear compilaciones de Gradle en GitHub ActionsCachee las dependencias y la caché de compilación de Gradle en GitHub Actions con gradle/actions/setup-gradle o actions/cache. Claves, PR de solo lectura.