Was ist ein Cache-Schlüssel in GitHub Actions?
Zuletzt aktualisiert am
Ein Cache-Key ist die Zeichenkette, mit der GitHub Actions einen gespeicherten Cache findet. Gibt es einen Cache mit exakt passendem Key, wird er wiederhergestellt. Falls nicht, meldet der Schritt einen Cache-Miss, Ihr Job erstellt die Daten neu und speichert sie anschließend unter diesem Key.
So funktioniert es
actions/cache benötigt einen path zum Speichern, einen key und optional restore-keys. Beim Wiederherstellen sucht die Aktion zunächst nach einer exakten Übereinstimmung mit dem key. Wird keine gefunden, prüft sie jeden Eintrag aus restore-keys als Präfix und verwendet den neuesten Cache, der damit beginnt. Ein Präfix-Treffer stellt ältere Daten wieder her, was meist besser ist als nichts. Am Ende des Jobs wird ein neuer Cache unter dem vollständigen Key gespeichert.
Caches sind unveränderlich. Einen Key können Sie nicht überschreiben, daher ändert ein guter Key sich genau dann, wenn sich der gecachte Inhalt ändern soll. Üblich ist, die Lockfile zu hashen.
Beispiel
- uses: actions/cache@v4
with:
path: ~/.npm
key: npm-${{ runner.os }}-${{ hashFiles('**/package-lock.json') }}
restore-keys: |
npm-${{ runner.os }}-
Hier ändert sich der Key, sobald sich die Lockfile ändert. In diesem Fall stellt das restore-keys-Präfix den vorherigen Cache wieder her, npm lädt nur die Differenz herunter, und ein neuer Cache wird gespeichert.
Gute Keys aufbauen
- Beginnen Sie mit einem stabilen Präfix, das beschreibt, was gecacht wird (
npm,cargo,gradle). - Ergänzen Sie
runner.osund die Architektur, wenn der Inhalt plattformspezifisch ist. - Ergänzen Sie
hashFiles()für die Dateien, die den Inhalt definieren (Lockfiles, Build-Dateien). - Fügen Sie eine manuelle Versionsnummer (
v2) hinzu, damit Sie den Cache gezielt ungültig machen können.
Der Cache-Key-Builder erzeugt Keys für gängige Stacks. Das vollständige Bild finden Sie unter Caching in GitHub Actions.
Häufige Fehler
- Key auf Basis von
github.sha. Jeder Commit erhält einen neuen Key, sodass Sie den Cache nie treffen. - Zu wenig oder zu viel hashen. Hashen Sie Quelldateien, ändern sich die Keys ständig. Hashen Sie nichts, veralten die Caches.
- Keine
restore-keys. Eine geänderte Abhängigkeit löst dann einen vollständigen statt eines inkrementellen Neuaufbaus aus. - Scope-Regeln übersehen. Auf einem Branch gespeicherte Caches sind nur für diesen Branch und seinen Basis-Branch sichtbar, nicht für parallele Branches.
- Größenlimits erreichen. Repositories haben eine maximale Gesamtgröße für Caches, ältere Einträge werden entfernt. Siehe Cache-Limits.
Verwandte Begriffe
FAQ
Kann ich einen bestehenden Cache aktualisieren?
Nein. Keys sind unveränderlich. Ändern Sie den Key (zum Beispiel über den Lockfile-Hash), dann wird ein neuer Cache gespeichert.
Was macht restore-keys?
Es stellt Fallback-Präfixe bereit, mit denen der nächstliegende ältere Cache wiederhergestellt wird, wenn der exakte Key nicht passt.
Wie leere ich einen Cache?
Löschen Sie ihn auf der Seite „Actions-Caches“ des Repositorys oder mit der GitHub CLI. Alternativ erhöhen Sie eine Versionsangabe im Key.
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.
- Gradle-Builds in GitHub Actions cachenGradle-Abhängigkeiten und Build-Cache in GitHub Actions mit gradle/actions/setup-gradle oder actions/cache cachen. Keys, PRs, Bereinigung, Checks.
- 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.