Zum Inhalt springen

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

  1. Beginnen Sie mit einem stabilen Präfix, das beschreibt, was gecacht wird (npm, cargo, gradle).
  2. Ergänzen Sie runner.os und die Architektur, wenn der Inhalt plattformspezifisch ist.
  3. Ergänzen Sie hashFiles() für die Dateien, die den Inhalt definieren (Lockfiles, Build-Dateien).
  4. 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.

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.