Gradle-Builds in GitHub Actions cachen
Zuletzt aktualisiert am
Um Gradle in GitHub Actions zu cachen, verwenden Sie gradle/actions/setup-gradle. Die Action cached das Gradle User Home (Abhängigkeiten, Wrapper, Build-Cache) und übernimmt Schlüssel, Bereinigung und das Verhalten im Nur-Lese-Modus für Sie. Ein selbst geschriebenes actions/cache für ~/.gradle/caches funktioniert, deckt aber das meiste davon nicht ab.
Option 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
Das ist das gesamte Setup. Führen Sie Gradle über den Wrapper (./gradlew) nach der Action aus, denn der Cache der Action wird am Ende des Jobs gespeichert. Sie benötigen weder actions/cache noch einen key.
Was die Action cached, laut der setup-gradle-Dokumentation (Stand Oktober 2026): Standardmäßig nutzt sie das erweiterte Caching der caches-Unterverzeichnisse im Gradle User Home, darunter heruntergeladene Abhängigkeiten (modules-2), Transforms, generierte Jars, den Cache für Kotlin-DSL-Skripte und den lokalen Build-Cache sowie Wrapper-Distributionen. Ein Basismodus cached nur ~/.gradle/caches und ~/.gradle/wrapper.
Nur Lesen auf Branches, Schreiben auf main
Standardmäßig schreiben nur Jobs auf dem Standard-Branch in den Cache. Jobs auf anderen Branches lesen den vorhandenen Cache und speichern nicht. So füllen Pull Requests Ihr 10-GB-Kontingent nicht mit nahezu identischen Einträgen, allerdings muss main einen Gradle-Build ausführen, um den Cache zu befüllen.
- uses: gradle/actions/setup-gradle@v6
with:
cache-read-only: ${{ github.ref != 'refs/heads/main' }}
Dieser Ausdruck ist das Standardverhalten und wird hier gezeigt, damit Sie es anpassen können. Beispielsweise können Sie erreichen, dass auch ein Release-Branch schreibt. Die Dokumentation beschreibt das Überschreiben mit cache-read-only, einschließlich Branch-Ausdrücken.
Bereinigung
cache-cleanup entfernt nicht mehr benötigte Dateien aus dem Gradle User Home, bevor der Cache gespeichert wird. Mögliche Werte sind on-success (Standard), always und never. Sie läuft nie, wenn der Cache schreibgeschützt oder deaktiviert ist. Behalten Sie den Standard bei: Ohne sie sammelt sich im Cache jede Version jeder Abhängigkeit an, die Ihr Projekt je verwendet hat.
Verschlüsselung des Configuration Cache
Wenn Sie den Configuration Cache von Gradle verwenden, können Einträge Geheimnisse enthalten. setup-gradle akzeptiert einen cache-encryption-key (einen Base64-AES-Schlüssel, den Sie mit openssl rand -base64 16 erzeugen und als Secret speichern können), sodass die Einträge im GitHub-Cache verschlüsselt werden.
Option 2: explizites actions/cache
- 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 }}-
Verwenden Sie dies, wenn Sie Actions von Drittanbietern vermeiden müssen, wobei gradle/actions vom Gradle-Projekt gepflegt wird. Sie verzichten dann auf die automatische Bereinigung, den branchabhängigen Nur-Lese-Modus und die jobspezifischen Schlüssel. Ohne Bereinigung legen restore-keys immer neue Einträge über alte, und der Cache wächst bis zur Entfernung.
Der Gradle-Build-Cache und der Remote-Cache
Zwei Caches sind im Spiel:
- Abhängigkeits-Cache (
modules-2): heruntergeladene Jars. Beide oben genannten Optionen übernehmen das. - Build-Cache: Task-Ergebnisse, die wiederverwendet werden, wenn die Eingaben übereinstimmen. Aktivieren Sie ihn mit
org.gradle.caching=trueingradle.propertiesoder mit--build-cache. setup-gradle speichert den lokalen Build-Cache im GitHub-Cache, sodass ein PR Kompilier- und Testergebnisse vonmainwiederverwenden kann.
Für größere Teams wird ein Remote-Build-Cache-Node (Develocity oder ein selbst gehosteter build-cache-node) über Jobs und Entwickler hinweg geteilt und ist nicht durch die 10 GB von GitHub begrenzt. Hinweise zur Einrichtung finden Sie in den Build-Cache-Dokumenten von Gradle.
Ergänzen Sie außerdem org.gradle.parallel=true und prüfen Sie org.gradle.workers.max. Gradle verwendet standardmäßig die Anzahl der CPU-Kerne, daher hilft eine größere Maschine ohne Konfigurationsänderung. In der gemessenen Benchmark von compiler.dev sank die CI-Laufzeit eines Angular-, Spring-Boot-(Gradle-) und Postgres-Projekts von 6m57s auf GitHub-gehosteten Runnern auf 2m18s (siehe Benchmarks).
Was Sie cachen sollten und was nicht
| Pfad | Cachen? | Hinweise |
|---|---|---|
~/.gradle/caches | Ja | Abhängigkeiten und Build-Cache |
~/.gradle/wrapper | Ja | Die Gradle-Distribution; vermeidet einen Download pro Lauf |
.gradle/ im Projekt | Vorsicht | Enthält Daten des Configuration Cache; setup-gradle übernimmt die Verwaltung |
build/-Verzeichnisse | Nein | Verwenden Sie stattdessen den Build-Cache; Ergebnisse enthalten absolute Pfade |
~/.m2 | Separat | Nur wenn Sie in Maven local veröffentlichen oder daraus lesen |
So überprüfen Sie einen Cache-Treffer
- Die setup-gradle-Zusammenfassung auf der Job-Seite listet wiederhergestellte und gespeicherte Cache-Einträge sowie deren Größen auf.
- In der Gradle-Ausgabe bedeutet
FROM-CACHEneben einem Task, dass sein Ergebnis aus dem Build-Cache stammt.UP-TO-DATEbedeutet unverändert lokal. - Abhängigkeits-Downloads sollten bei einem warmen Lauf nicht in der
--info-Ausgabe erscheinen. gh cache list --key gradle --limit 20zeigt Einträge und die letzte Verwendung.
Häufige Fehler
- Kein Cache auf main befüllt. Bei schreibgeschützten Branches wird nichts gespeichert, bis ein Build auf dem Standard-Branch läuft.
- Gradle läuft vor der Setup-Action. Platzieren Sie die Action immer zuerst.
- Zu wenig in einem manuellen Schlüssel gehasht. Versionskataloge und Wrapper-Properties einbeziehen.
- Caching von
build/. Das Verzeichnis ist groß und passt nicht zwischen Commits. - Größe ignorieren. Android- und Multi-Modul-Builds erzeugen Caches im Multi-GB-Bereich. Siehe Cache-Limits.
FAQ
Brauche ich mit setup-gradle noch actions/cache?
Nein. setup-gradle ersetzt es für das Gradle User Home. Behalten Sie actions/cache für andere Zwecke wie Node oder Docker.
Funktioniert das auch mit Maven?
setup-gradle unterstützt nur Gradle. Für Maven cachen Sie ~/.m2/repository mit actions/setup-java und cache: maven oder actions/cache mit dem Schlüssel **/pom.xml.
Warum ist mein erster PR-Build trotz Caching langsam?
Wenn main den Cache noch nicht befüllt hat oder der Cache entfernt wurde, startet ein PR ohne Cache. Starten Sie einen Build auf main.
Kann ich den Gradle-Daemon in der CI verwenden?
Jeder neue Job startet ohnehin einen neuen Daemon. setup-gradle setzt sinnvolle Standardwerte, die Sie selten ändern müssen.
Nächste Schritte
Verwandt: Gradle-Builds insgesamt beschleunigen, Docker-Layer-Caching, falls Ihr Gradle-Build Images erzeugt, und wie Sie GitHub Actions beschleunigen. Unter compiler.dev Preise können Sie denselben Build auf einer Maschine mit 8 vCPU testen.
Verwandt
- Cargo- und Rust-Builds in GitHub Actions cachenCargo-Registry, Git-Abhängigkeiten und Target-Verzeichnis in GitHub Actions mit Swatinem/rust-cache oder actions/cache cachen, ohne aufgeblähte Caches.
- Go-Module und Build-Cache in GitHub Actions cachenGo-Module (GOMODCACHE) und Build-Cache (GOCACHE) in GitHub Actions mit setup-go oder actions/cache cachen. Keys, go.sum und Cache-Treffer prüfen.
- npm-Abhängigkeiten in GitHub Actions cachennpm-Abhängigkeiten in GitHub Actions cachen, mit setup-node oder actions/cache. Funktionierendes YAML, der richtige Key, warum nicht node_modules, und Treffer prüfen.
- pip-Abhängigkeiten in GitHub Actions cachenpip in GitHub Actions mit setup-python oder actions/cache cachen, dazu die schnellere uv-Option. Schlüssel, Nicht-Cache-Inhalte und Trefferprüfung.