Referenz zum Zwischenspeichern von Abhängigkeiten

Nutzung der cache-Aktion

Durch die cache-Aktion wird versucht beim Wiederherstellen eines Caches versucht, die folgende Sequenz auszuführen:

1. Zunächst wird nach einer genauen Übereinstimmung mit dem bereitgestellten key-Element gesucht.
2. Wenn keine genaue Übereinstimmung gefunden wird, wird nach teilweisen Übereinstimmungen für das key-Element gesucht.
3. Wenn trotzdem keine Übereinstimmung gefunden wurde und du restore-keys angegeben hast, werden diese Schlüssel sequenziell auf teilweise Übereinstimmung überprüft. Weitere Informationen findest du unter Abgleichen eines Cacheschlüssels.

Wenn es eine genaue Übereinstimmung mit dem angegebenen key gibt, wird dies als Cachetreffer gewertet. Wenn kein Cache genau mit den angegebenen key übereinstimmt, wird dies als Cachefehler gewertet. Bei einem Cachefehler erstellt die Aktion automatisch einen neuen Cache, wenn der Auftrag erfolgreich abgeschlossen wurde. Der neue Cache verwendet den bereitgestellten key und enthält die von Ihnen in path angegebenen Dateien. Weitere Informationen zur Handhabung dieser Situation findest du unter Cachetreffer und -fehler.

Du kannst den Inhalt eines vorhandenen Caches nicht ändern. Stattdessen kannst du einen neuen Cache mit einem neuen Schlüssel erstellen.

Eingabeparameter für die cache-Aktion

• key: Erforderlich. Der Schlüssel, der beim Speichern eines Caches erstellt wurde, und der Schlüssel, der zum Suchen nach einem Cache verwendet wird. Dies kann eine beliebige Kombination von Variablen, Kontextwerten, statischen Zeichenfolgen und Funktionen sein. Schlüssel haben eine maximale Länge von 512 Zeichen und Schlüssel, die die maximale Länge überschreiten, lassen die Aktion fehlschlagen.

• path: Erforderlich. Die Pfade auf dem Runner, die zwischengespeichert oder wiederhergestellt werden sollen.

  • Du kannst einen einzelnen Pfad angeben oder mehrere Pfade in separaten Zeilen hinzufügen. Beispiel:

    - name: Cache Gradle packages
      uses: actions/cache@v4
      with:
        path: |
          ~/.gradle/caches
          ~/.gradle/wrapper
    

  • Du kannst entweder Verzeichnisse oder einzelne Dateien angeben, und Globmuster werden unterstützt.

  • Du kannst absolute Pfade oder zum Arbeitsbereichsverzeichnis relative Pfade angeben.

• restore-keys: Optional. Eine Zeichenfolge mit alternativen Wiederherstellungsschlüsseln, wobei jeder Wiederherstellungsschlüssel in einer neuen Zeile platziert wird. Wenn kein Cachetreffer für key vorhanden ist, werden diese Wiederherstellungsschlüssel sequenziell in der bereitgestellten Reihenfolge verwendet, um einen Cache zu finden und wiederherzustellen. Beispiel:

  restore-keys: |
    npm-feature-${{ hashFiles('package-lock.json') }}
    npm-feature-
    npm-
  

• enableCrossOsArchive: Optional Ein boolescher Wert, bei dessen Aktivierung Windows-Runner Caches speichern oder wiederherstellen können, und zwar unabhängig vom Betriebssystem, auf dem der Cache erstellt wurde. Wird dieser Parameter nicht definiert, ist er standardmäßig auf false festgelegt. Weitere Informationen findest du unter Betriebssystemübergreifender Cache in der Dokumentation zum Actions-Cache.

Ausgabeparameter für die cache-Aktion

• cache-hit: Ein boolescher Wert, der angibt, dass eine genaue Übereinstimmung für den Schlüssel gefunden wurde.

Cachetreffer und -fehler

Wenn key exakt mit einem vorhandenen Cache übereinstimmt, wird dies als Cachetreffer bezeichnet, und die Aktion stellt die zwischengespeicherten Dateien im Verzeichnis path wieder her.

Wenn key nicht mit einem vorhandenen Cache übereinstimmt, wird das als Cachefehler bezeichnet. Wenn der Auftrag erfolgreich abgeschlossen wird, wird automatisch ein neuer Cache erstellt.

Wenn ein Cachefehler auftritt, sucht die Aktion auch in den angegebenen restore-keys nach Übereinstimmungen:

1. Wenn du restore-keys angibst, sucht die cache-Aktion sequenziell nach Caches, die der Liste von restore-keys entsprechen.
   • Wenn es eine genaue Übereinstimmung gibt, stellt die Aktion die Dateien aus dem Cache im Verzeichnis path wieder her.
   • Wenn es keine exakten Übereinstimmungen gibt, sucht die Aktion nach partiellen Übereinstimmungen der „restore keys“ (Wiederherstellungs-Scvhlüssel). Wenn die Aktion eine partielle Übereinstimmung findet, wird der aktuellste Cache im Verzeichnis path wiederhergestellt.
2. Die cache-Aktion wird abgeschlossen, und der nächste Schritt im Auftrag wird ausgeführt.
3. Wenn der Auftrag erfolgreich abgeschlossen wurde, erstellt die Aktion automatisch einen neuen Cache mit dem Inhalt des Verzeichnisses path.

Eine ausführlichere Erläuterung des Cacheabgleichs findest du unter Abgleichen eines Cacheschlüssels.

Beispiel für die Verwendung der cache-Aktion

Dieses Beispiel erstellt einen neuen Cache, wenn sich die Pakete in package-lock.json ändern oder sich das Betriebssystem des Runners ändert. Das folgende Beispiel verwendet Kontexte und Ausdrücke, um einen Schlüssel zu generieren, der eine Kennung des Runnerbetriebssystems und einen SHA-256-Hash der Datei package-lock.json enthält.

name: Caching with npm
on: push
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Cache node modules
        id: cache-npm
        uses: actions/cache@v4
        env:
          cache-name: cache-node-modules
        with:
          # npm cache files are stored in `~/.npm` on Linux/macOS
          path: ~/.npm
          key: ${{ runner.os }}-build-${{ env.cache-name }}-${{ hashFiles('**/package-lock.json') }}
          restore-keys: |
            ${{ runner.os }}-build-${{ env.cache-name }}-
            ${{ runner.os }}-build-
            ${{ runner.os }}-

      - if: ${{ steps.cache-npm.outputs.cache-hit != 'true' }}
        name: List the state of node modules
        continue-on-error: true
        run: npm list

      - name: Install dependencies
        run: npm install

      - name: Build
        run: npm run build

      - name: Test
        run: npm test

name: Caching with npm
on: push
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Cache node modules
        id: cache-npm
        uses: actions/cache@v4
        env:
          cache-name: cache-node-modules
        with:
          # npm cache files are stored in `~/.npm` on Linux/macOS
          path: ~/.npm
          key: ${{ runner.os }}-build-${{ env.cache-name }}-${{ hashFiles('**/package-lock.json') }}
          restore-keys: |
            ${{ runner.os }}-build-${{ env.cache-name }}-
            ${{ runner.os }}-build-
            ${{ runner.os }}-

      - if: ${{ steps.cache-npm.outputs.cache-hit != 'true' }}
        name: List the state of node modules
        continue-on-error: true
        run: npm list

      - name: Install dependencies
        run: npm install

      - name: Build
        run: npm run build

      - name: Test
        run: npm test

Cache-Keys aus Kontexten erstellen

Ein Cache-Key (Cache-Schlüssel) kann Kontexte, Funktionen, Literale und Operatoren enthalten, die von GitHub Actions unterstützt werden. Weitere Informationen findest du unter Kontextreferenz und Auswerten von Ausdrücken in Workflows und Aktionen.

Wenn du zum Erstellen eines keys Ausdrücke verwendest, kannst du automatisch einen neuen Cache erstellen, wenn sich Abhängigkeiten ändern.

Du kannst z. B. einen key mit einem Ausdruck erstellen, der den Hash einer npm-Datei package-lock.json berechnet. Wenn sich also die Abhängigkeiten ändern, aus denen die Datei package-lock.json besteht, ändert sich der Cacheschlüssel, und ein neuer Cache wird automatisch erstellt.

npm-${{ hashFiles('package-lock.json') }}

GitHub wertet den Ausdruck hash "package-lock.json" aus, um den endgültigen key abzuleiten.

npm-d5ea0750

Verwenden der Ausgabe der cache-Aktion

Du kannst die Ausgabe der cache-Aktion verwenden, um eine Aktion abhängig davon auszuführen, ob ein Cachetreffer oder -fehler aufgetreten ist. Wenn eine genaue Übereinstimmung für einen Cache des angegebenen key-Elements gefunden wird, wird die Ausgabe von cache-hit auf true festgelegt.

Im Beispielworkflow oben gibt es einen Schritt, in dem der Status der Node-Module aufgelistet wird, wenn ein Cachefehler aufgetreten ist:

- if: ${{ steps.cache-npm.outputs.cache-hit != 'true' }}
  name: List the state of node modules
  continue-on-error: true
  run: npm list

Abgleichen eines Cacheschlüssels

Die Aktion cache sucht zunächst nach Cachetreffern für key und den Cache Version in dem Branch, der die Workflowausführung enthält. Wenn kein Treffer vorhanden ist, wird nach Präfixübereinstimmungen für key gesucht. Sollten dabei trotzdem kein Treffer gefunden werden, wird nach restore-keys und der Version gesucht. Wenn im aktuellen Branch immer noch keine Treffer vorhanden sind, führt die cache-Aktion dieselben Schritte im Standardbranch erneut aus. Beachte, dass während der Suche die Bereichseinschränkungen gelten. Weitere Informationen findest du unter Einschränkungen für das Zugreifen auf einen Cache.

Über die Cacheversion kann ein Cache mit Metadaten für den path und das bei der Cacheerstellung verwendete Komprimierungstool versehen werden. So wird sichergestellt, dass die Workflowausführung eindeutig einem Cache entspricht, den sie tatsächlich dekomprimieren und nutzen kann. Weitere Informationen findest du unter Cacheversion in der Dokumentation zum Actions-Cache.

restore-keys ermöglicht es Ihnen, eine Liste alternativer Wiederherstellungsschlüssel anzugeben, die verwendet werden sollen, wenn ein Cachefehler für key auftritt. Du kannst mehrere restore-keys erstellen, die von den spezifischsten zum am wenigsten spezifischen sortiert sind. Die cache-Aktion durchsucht die restore-keys sequenzielle Reihenfolge. Wenn ein Schlüssel nicht direkt übereinstimmt, sucht die Aktion nach Schlüsseln denen der Restore-Key vorangestellt ist. Wenn mehrere Teiltreffer für einen Restore-Key vorhanden sind, gibt die Aktion den zuletzt erstellten Cache zurück.

Beispiel für die Verwendung mehrerer Restore-Keys

restore-keys: |
  npm-feature-${{ hashFiles('package-lock.json') }}
  npm-feature-
  npm-

Der Runner wertet die Ausdrücke aus, die in die folgenden restore-keys aufgelöst werden:

restore-keys: |
  npm-feature-d5ea0750
  npm-feature-
  npm-

Der Wiederherstellungsschlüssel npm-feature- stimmt mit jedem Schlüssel überein, der mit der Zeichenfolge npm-feature- beginnt. Beispielsweise entsprechen beide Schlüssel npm-feature-fd3052de und npm-feature-a9b253ff dem Wiederherstellungsschlüssel. Der Cache mit dem neuesten Erstellungsdatum wird verwendet. Die Schlüssel in diesem Beispiel werden in der folgenden Reihenfolge durchsucht:

1. npm-feature-d5ea0750 stimmt mit einem bestimmten Hash überein.
2. npm-feature- gleicht Cacheschlüssel mit dem Präfix npm-feature- ab.
3. npm- gleicht alle Schlüssel mit dem Präfix npm- ab.

Beispiel für die Suchpriorität

key:
  npm-feature-d5ea0750
restore-keys: |
  npm-feature-
  npm-

Wenn beispielsweise ein Pull Request einen feature-Branch enthält und auf den Standardbranch (main) abzielt, sucht die Aktion nach key und restore-keys in der folgenden Reihenfolge:

1. Schlüssel npm-feature-d5ea0750 im feature-Branch
2. Schlüssel npm-feature- im feature-Branch
3. Schlüssel npm- im feature-Branch
4. Schlüssel npm-feature-d5ea0750 im main-Branch
5. Schlüssel npm-feature- im main-Branch
6. Schlüssel npm- im main-Branch

setup-*-Aktionen für bestimmte Paket-Manager

Wenn du die unten aufgeführten Paket-Manager zwischenspeicherst, erfordert die Verwendung ihrer jeweiligen setup-*-Aktionen minimale Konfiguration und erstellt Abhängigkeitscaches für dich und stellt diese wieder her.

Einschränkungen für den Zugriff auf einen Cache

Zugriffsbeschränkungen bieten Cache-Isolation und Sicherheit durch Ziehen einer logischen Grenze zwischen Branches oder Tags. Mit Workflowausführungen können Caches wiederhergestellt werden, die entweder im aktuellen Branch oder im Standardbranch (üblicherweise main) erstellt wurden. Wenn eine Workflowausführung für einen Pull Request ausgelöst wird, kann sie auch Caches wiederherstellen, die im Basisbranch erstellt wurden, einschließlich der Basisbranches von geforkten Repositorys. Wenn der Branch feature-b beispielsweise den Basisbranch feature-a verwendet, hat ein Workflow, der durch einen Pull Request ausgelöst wird, Zugriff auf die Caches, die im Standardbranch main, dem Basisbranch feature-a und dem aktuellen Branch feature-b erstellt wurden.

Mit Workflowausführungen können keine Caches wiederhergestellt werden, die für untergeordnete oder gleichgeordnete Branches erstellt wurden. Beispielsweise wäre ein für den untergeordneten Branch feature-b erstellter Cache nicht für einen Workflow zugänglich, der für den übergeordneten Branch main ausgelöst wurde. Ebenso wäre ein Cache, der für den Branch feature-a mit der Basis main erstellt wurde, nicht für den gleichgeordneten Branch feature-c mit der Basis main zugänglich. Mithilfe von Workflowausführungen können auch keine Caches wiederhergestellt werden, die für andere Tagnamen erstellt wurden. Zum Beispiel wäre ein Cache, der für das Tag release-a mit der Basis main erstellt wurde, nicht für eine Workflowausführung zugänglich, die für das Tag release-b mit der Basis main ausgelöst wurde.

Wenn ein Cache über eine Workflowausführung erstellt wird, die durch einen Pull Request ausgelöst wurde, wird der Cache für den Mergeverweis (refs/pull/.../merge) erstellt. Aus diesem Grund hat der Cache einen begrenzten Bereich und kann nur durch erneutes Ausführen des Pull Request wiederhergestellt werden. Er kann nicht über den Basisbranch oder andere Pull Requests wiederhergestellt werden, die diesen Basisbranch als Ziel haben.

Mehrere Workflowausführungen in einem Repository können Caches gemeinsam nutzen. Ein Cache, der für einen Branch in einer Workflowausführung erstellt wurde, kann von einer anderen Workflowausführung für dasselbe Repository und denselben Branch aufgerufen und wiederhergestellt werden.

Nutzungsbeschränkungen und Räumungsrichtlinien

GitHub wird alle Cache-Einträge entfernen, auf die seit mehr als 7 Tagen nicht zugegriffen wurde. Es gibt keine Grenze für die Anzahl der Caches, die du speichern kannst, aber die Gesamtgröße aller Caches in einem Repository ist begrenzt. Standardmäßig liegt der Grenzwert bei 10 GB pro Repository. Dieser Grenzwert kann jedoch je nach den von deinen Unternehmensinhaberinnen oder Repositoryadministratorinnen festgelegten Richtlinien abweichen. Sobald ein Repository seinen maximalen Cachespeicher erreicht hat, erstellt die Cache-Löschrichtlinie Speicherplatz, indem die Caches in der Reihenfolge des letzten Zugriffsdatums gelöscht werden, von der ältesten bis zur neuesten.

Wenn du diesen Grenzwert überschreitest, wird GitHub den neuen Cache speichern, jedoch auch damit beginnen, Caches zu löschen, bis die Gesamtgröße kleiner als das Limit des Repositorys ist. Der Prozess zur Cacheleerung kann zu einem sogenannten Cache-Thrashing führen, bei dem Caches in hoher Frequenz erstellt und gelöscht werden. Um dies zu reduzieren, kannst du die Caches für ein Repository überprüfen und Korrekturmaßnahmen ergreifen, wie z. B. das Entfernen der Zwischenspeicherung aus bestimmten Workflows. Weitere Informationen findest du unter Verwalten von Caches. Du kannst auch die Cachegrößenbeschränkung für ein Repository erhöhen. Weitere Informationen finden Sie unter Verwalten von GitHub Actions-Einstellungen für ein Repository.

Nächste Schritte

Informationen zum Verwalten von Abhängigkeitscaches findest du unter Verwalten von Caches.