Zum Inhalt springen

Caching in GitHub Actions: Schlüssel, Limits, Beispiele

Zuletzt aktualisiert am

Ein gutes Cache verwandelt eine dreiminütige Abhängigkeitsinstallation in zehn Sekunden. Ein schlechter Cache spart nichts oder stellt schlimmstenfalls veraltete Dateien wieder her, die Ihren Build brechen. Dieser Guide erklärt, wie GitHub Actions beim Cache entscheidet, was wiederhergestellt wird, wie Sie Keys schreiben und mit welchen Limits Sie rechnen sollten.

Die zwei Wege zum Caching

Integriertes Caching in setup-Actions. Für gängige Ökosysteme genügt eine Zeile:

- uses: actions/setup-node@v4
  with:
    node-version: 22
    cache: pnpm          # npm, yarn or pnpm
- uses: actions/setup-python@v5
  with:
    python-version: "3.13"
    cache: pip
- uses: actions/setup-go@v5
  with:
    go-version-file: go.mod

Diese cachen das Download-Verzeichnis des Paketmanagers, gesteuert über das Lockfile. setup-go cached standardmäßig. Verwenden Sie diese Varianten, wo sie passen; es gibt dann nichts zu pflegen.

actions/cache für alles Übrige. Pfad und Key legen Sie selbst fest:

- uses: actions/cache@v4
  with:
    path: |
      ~/.gradle/caches
      ~/.gradle/wrapper
    key: gradle-${{ runner.os }}-${{ hashFiles('**/*.gradle*', '**/gradle-wrapper.properties') }}
    restore-keys: |
      gradle-${{ runner.os }}-

So funktioniert das Key-Matching

Bei einer Cache-Abfrage sucht GitHub zuerst nach einer exakten Übereinstimmung mit key. Gibt es keine, probiert es jede Zeile von restore-keys der Reihe nach und wählt den zuletzt erstellten Cache, dessen Key mit diesem Präfix beginnt. Bei einem exakten Treffer setzt die Action cache-hit auf true und überspringt den Speicherschritt am Ende des Jobs. Bei einem Teiltreffer über restore-keys läuft der Job, und anschließend wird ein neuer Cache unter dem vollständigen key gespeichert.

Genau dieses Verhalten macht restore-keys so nützlich. Ändert sich Ihr Lockfile um eine Abhängigkeit, schlägt der exakte Key fehl, das Präfix stellt aber den Cache von gestern wieder her, sodass die Installation nur die Differenz herunterlädt.

Ein guter Key besteht aus drei Teilen: Betriebssystem und Architektur, der Tool-Version und einem Hash der Eingabedateien.

key: cargo-${{ runner.os }}-${{ runner.arch }}-${{ hashFiles('**/Cargo.lock') }}

Der Cache-Key-Generator erstellt Keys und restore-keys für gängige Stacks.

Gültigkeitsbereich und Limits

Diese Angaben stammen aus GitHubs Dokumentation zu Dependency-Caching und Nutzungslimits:

  • Ein Workflow kann Caches wiederherstellen, die auf dem aktuellen Branch und auf dem Basis-Branch (sowie dem Standard-Branch) erstellt wurden. Ein Feature-Branch kann den Cache von main lesen; main kann den Cache eines Feature-Branches nicht lesen. Parallele Branches können sich gegenseitig nicht lesen.
  • Bei Pull Requests sind Caches auf den Merge-Ref beschränkt, sodass der Cache eines PRs nicht von einem anderen PR wiederverwendet werden kann.
  • Caches, auf die 7 Tage lang nicht zugegriffen wurde, werden entfernt.
  • Der Standardspeicher für Caches beträgt insgesamt 10 GB pro Repository. Wird dieses Limit überschritten, entfernt GitHub die zuletzt genutzten Caches zuerst. Eigentümer können das Limit erhöhen; Speicher oberhalb des enthaltenen Umfangs wird berechnet.
  • Cache-Einträge sind unveränderlich. Sie können einen Key nicht aktualisieren, sondern nur einen neuen erstellen.

Die praktische Konsequenz: Stellen Sie sicher, dass main den Cache befüllt. Führen Sie denselben Cache-Schritt bei Pushes auf main aus, damit jeder PR mit einem vorgewärmten Cache startet.

Was gecacht werden sollte und was nicht

Diesen cachenSchlüsselDarauf verzichten
Download-Cache von npm, pnpm, yarnpackage-lock.json, pnpm-lock.yaml, yarn.locknode_modules selbst
Download-Cache von pip, Poetry, uvrequirements*.txt, poetry.lock, uv.lockVollständige virtualenvs über Python-Versionen hinweg
Gradle, MavenBuild-Dateien, Wrapper-EigenschaftenBuild-Ausgaben mit absoluten Pfaden
CargoCargo.locktarget/ eines riesigen Workspaces, oft größer als die eingesparte Zeit
Compiler-Caches (ccache, sccache)Betriebssystem, Compiler-VersionNichts; diese lohnen sich immer

Große Caches haben ihren Preis. Ein 2 GB großer Cache, dessen Download und Entpacken 40 Sekunden dauert, schlägt womöglich keine 30 Sekunden lange Installation. Messen Sie die Wiederherstellungszeit im Schritt-Log.

Häufige Ursachen für Cache-Misses

  1. Der Key enthält etwas, das sich bei jedem Lauf ändert, etwa github.sha oder einen Zeitstempel. Verwenden Sie das nur als letzten Teil eines Keys, zusammen mit restore-keys für rollierende Caches.
  2. hashFiles findet keine Dateien. Die Funktion liefert einen leeren String, sodass jeder Lauf denselben Key verwendet und nie aktualisiert. Prüfen Sie das Glob-Muster.
  3. Anderes Betriebssystem oder andere Architektur. Nehmen Sie runner.os und runner.arch in den Key auf.
  4. Pfad unterscheidet sich zwischen Speichern und Wiederherstellen. Pfade sind Teil der Cache-Identität.
  5. Branch-Gültigkeitsbereich. Ein neuer Branch sieht nur seine eigenen Caches und die des Standard-Branches.
  6. Entfernung. Prüfen Sie die Liste der Actions-Caches im Repository. Bei vielen Branches füllen sich 10 GB schnell.

Caches aus der CLI auflisten und löschen:

gh cache list --limit 50
gh cache delete <cache-id>

Rollierende Caches für Build-Ausgaben

Bei inkrementellen Compilern soll jeder Lauf bei der Ausgabe des letzten Laufs beginnen und danach die neue speichern. Verwenden Sie einen eindeutigen Schlüssel mit einem Präfix als Fallback:

- uses: actions/cache@v4
  with:
    path: .turbo
    key: turbo-${{ runner.os }}-${{ github.sha }}
    restore-keys: |
      turbo-${{ runner.os }}-

Jeder Lauf verfehlt den exakten Schlüssel, stellt den neuesten Präfix-Treffer wieder her und speichert einen neuen Eintrag. Achten Sie bei diesem Muster auf das Limit von 10 GB; die ältesten Einträge werden automatisch entfernt.

Wiederherstellen und Speichern trennen

Verwenden Sie actions/cache/restore und actions/cache/save, um nur dann zu speichern, wenn der Job erfolgreich ist, oder nur aus main:

- uses: actions/cache/restore@v4
  id: cache
  with:
    path: ~/.m2
    key: m2-${{ hashFiles('**/pom.xml') }}
- run: mvn -B verify
- uses: actions/cache/save@v4
  if: github.ref == 'refs/heads/main' && steps.cache.outputs.cache-hit != 'true'
  with:
    path: ~/.m2
    key: m2-${{ hashFiles('**/pom.xml') }}

So verhindern Sie, dass Pull-Request-Branches Ihr Kontingent füllen.

FAQ

Wie groß kann ein Cache in GitHub Actions werden?

Die Gesamtgröße pro Repository beträgt standardmäßig 10 GB, wie in den Nutzungslimits von GitHub angegeben.

Kann ich einen Cache zwischen Workflows teilen?

Ja, sofern Schlüssel und Pfad übereinstimmen und der Branch-Scope es zulässt. Caches gehören zum Repository, nicht zu einem einzelnen Workflow.

Sollte ich hier auch Docker-Layer cachen?

Docker-Layer haben eigene Backends. Siehe Docker-Layer-Caching in CI.

Ist ein Cache-Treffer garantiert sicher?

Ein Treffer mit exaktem Schlüssel stellt genau das wieder her, was unter diesem Schlüssel gespeichert wurde. Die Sicherheit hängt davon ab, ob der Schlüssel jede Eingabe abdeckt, die die Dateien beeinflusst.

Wo das einzuordnen ist

Caching ist eine von mehreren Maßnahmen in so beschleunigen Sie GitHub Actions. Wenn Caching hilft, ein Job aber weiterhin langsam ist, prüfen Sie, ob der Job CPU-gebunden ist; der Vergleichsmodus von compiler.dev führt Ihre Jobs auf einer schnelleren Maschine aus, damit Sie den Unterschied in Ihrem eigenen Workflow sehen.

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

Kostenlos testen