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
mainlesen;mainkann 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 cachen | Schlüssel | Darauf verzichten |
|---|---|---|
| Download-Cache von npm, pnpm, yarn | package-lock.json, pnpm-lock.yaml, yarn.lock | node_modules selbst |
| Download-Cache von pip, Poetry, uv | requirements*.txt, poetry.lock, uv.lock | Vollständige virtualenvs über Python-Versionen hinweg |
| Gradle, Maven | Build-Dateien, Wrapper-Eigenschaften | Build-Ausgaben mit absoluten Pfaden |
| Cargo | Cargo.lock | target/ eines riesigen Workspaces, oft größer als die eingesparte Zeit |
| Compiler-Caches (ccache, sccache) | Betriebssystem, Compiler-Version | Nichts; 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
- Der Key enthält etwas, das sich bei jedem Lauf ändert, etwa
github.shaoder einen Zeitstempel. Verwenden Sie das nur als letzten Teil eines Keys, zusammen mitrestore-keysfür rollierende Caches. hashFilesfindet keine Dateien. Die Funktion liefert einen leeren String, sodass jeder Lauf denselben Key verwendet und nie aktualisiert. Prüfen Sie das Glob-Muster.- Anderes Betriebssystem oder andere Architektur. Nehmen Sie
runner.osundrunner.archin den Key auf. - Pfad unterscheidet sich zwischen Speichern und Wiederherstellen. Pfade sind Teil der Cache-Identität.
- Branch-Gültigkeitsbereich. Ein neuer Branch sieht nur seine eigenen Caches und die des Standard-Branches.
- 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.
Verwandt
- Docker-Layer-Caching in der CI mit BuildxDocker-Builds in GitHub Actions beschleunigen: buildx cache-from und cache-to, gha- und registry-Backends und ein Dockerfile für Cache-Treffer.
- TypeScript-Monorepo in GitHub Actions beschleunigenTypprüfung und Linting in TypeScript-Monorepos auf GitHub Actions beschleunigen: inkrementelles tsc, Projektreferenzen, Lint-Caches und parallele Jobs.
- Playwright im Monorepo mit GitHub Actions beschleunigenPlaywright-E2E-Tests in einem Node-Monorepo auf GitHub Actions beschleunigen: App einmal bauen, E2E überspringen, wenn sich die Web-App nicht ändert.
- CI-Geschwindigkeits-Badge in Ihre README einfügenZeigen Sie die Geschwindigkeit Ihrer CI mit einem README-Badge: die mediane Laufzeit Ihrer Repository-Workflows auf GitHub Actions, automatisch aktualisiert.