Zum Inhalt springen

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=true in gradle.properties oder mit --build-cache. setup-gradle speichert den lokalen Build-Cache im GitHub-Cache, sodass ein PR Kompilier- und Testergebnisse von main wiederverwenden 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

PfadCachen?Hinweise
~/.gradle/cachesJaAbhängigkeiten und Build-Cache
~/.gradle/wrapperJaDie Gradle-Distribution; vermeidet einen Download pro Lauf
.gradle/ im ProjektVorsichtEnthält Daten des Configuration Cache; setup-gradle übernimmt die Verwaltung
build/-VerzeichnisseNeinVerwenden Sie stattdessen den Build-Cache; Ergebnisse enthalten absolute Pfade
~/.m2SeparatNur wenn Sie in Maven local veröffentlichen oder daraus lesen

So überprüfen Sie einen Cache-Treffer

  1. Die setup-gradle-Zusammenfassung auf der Job-Seite listet wiederhergestellte und gespeicherte Cache-Einträge sowie deren Größen auf.
  2. In der Gradle-Ausgabe bedeutet FROM-CACHE neben einem Task, dass sein Ergebnis aus dem Build-Cache stammt. UP-TO-DATE bedeutet unverändert lokal.
  3. Abhängigkeits-Downloads sollten bei einem warmen Lauf nicht in der --info-Ausgabe erscheinen.
  4. gh cache list --key gradle --limit 20 zeigt Einträge und die letzte Verwendung.

Häufige Fehler

  1. Kein Cache auf main befüllt. Bei schreibgeschützten Branches wird nichts gespeichert, bis ein Build auf dem Standard-Branch läuft.
  2. Gradle läuft vor der Setup-Action. Platzieren Sie die Action immer zuerst.
  3. Zu wenig in einem manuellen Schlüssel gehasht. Versionskataloge und Wrapper-Properties einbeziehen.
  4. Caching von build/. Das Verzeichnis ist groß und passt nicht zwischen Commits.
  5. 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.

Diesen Gradle-Build auf compiler.dev ausführen Keine Karte nötig · 200 kostenlose Minuten

Kostenlos testen