Skip to main content

Abhängigkeiten zwischenspeichern um Workflows zu beschleunigen

Um deine Workflows schneller und effizienter zu gestalten, kannst du Caches für Abhängigkeiten und andere häufig wiederverwendete Dateien erstellen und verwenden.

Informationen zum Zwischenspeichern von Workflow-Abhängigkeiten

Workflow-Läufe verwenden häufig dieselben Ausgaben oder heruntergeladenen Abhängigkeiten in aufeinanderfolgenden Durchläufen. Tools zur Verwaltung von Paketen und Abhängigkeiten wie beispielsweise Maven, Gradle, npm und Yarn halten einen lokalen Cache mit heruntergeladenen Abhängigkeiten.

Um die Zeit zum Neuerstellen von Dateien wie Abhängigkeiten einzusparen, kann GitHub in Workflows häufig verwendete Dateien zwischenspeichern.

Um Abhängigkeiten für einen Auftrag zwischenzuspeichern, kannst du die cache-Aktion von GitHub verwenden. Die Aktion erstellt einen Cache, der durch einen eindeutigen Schlüssel identifiziert wird, und stellt diesen wieder her. 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.

Paket-ManagerSetup-*-Aktion zum Zwischenspeichern
npm, Yarn, pnpmsetup-node
pip, pipenv, Poetrysetup-python
Gradle, Mavensetup-java
RubyGemssetup-ruby
Go go.sumsetup-go

Warnung: Es wird empfohlen, keine vertraulichen Informationen im Cache zu speichern. Sensible Informationen umfassen beispielsweise Zugriffstoken oder Anmeldedaten, die in einer Datei im Cache-Pfad gespeichert sind. Auch Befehlszeilenprogramme (CLI) wie docker login können Anmeldeinformationen in einer Konfigurationsdatei speichern. Jeder Benutzer mit Lesezugriff kann einen Pull-Request für ein Repository erstellen und auf den Inhalt des Caches zugreifen. Forks eines Repositorys können auch Pull-Requests auf den base branch (Basiszweig) erstellen und auf Caches im Basiszweig zugreifen.

Vergleich: Artefakte v/s Zwischenspeicherung von Abhängigkeiten

Artefakte und Caching sind ähnlich, da sie die Möglichkeit bieten, Dateien auf GitHub zu speichern, aber die beiden Funktionalitäten bieten verschiedene Anwendungsfälle und dürfen nicht miteinander verwechselt werden.

  • Verwende die Zwischenspeicherung, wenn du Dateien wiederverwenden möchtest, die sich zwischen Aufträgen oder Workflowausführungen nur selten verändern, zum Beispiel Buildabhängigkeiten aus einem Paketverwaltungssystem.
  • Verwende Artefakte, wenn du von einem Auftrag generierte Dateien speichern möchtest, um diese nach einer Workflowausführung zu öffnen, zum Beispiel Binärdateien oder Buildprotokolle.

Weitere Informationen zu Workflowausführungsartefakten findest du unter Endgültiges Speichern von Workflowdaten mit Artefakten.

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.

Verwenden der cache-Aktion

Die cache-Aktion versucht, einen Cache basierend auf dem bereitgestellten key wiederherzustellen. Wenn die Aktion einen Cache findet, der exakt mit dem Schlüssel übereinstimmt, stellt die Aktion die zwischengespeicherten Dateien an dem von dir konfigurierten Pfad (path) wieder her. Du kannst optional eine Liste von restore-keys angeben, die verwendet werden sollen, falls key nicht mit einem vorhandenen Cache übereinstimmt. Eine Liste von restore-keys ist nützlich, wenn du einen Cache aus einem anderen Branch wiederherstellst, da restore-keys einen Teilabgleich für Cacheschlüssel durchführen kann. Weitere Informationen zum Abgleichen von restore-keys 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@v3
        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-
    

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.

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

      - name: Cache node modules
        id: cache-npm
        uses: actions/cache@v3
        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 Kontexte und Ausdrücke.

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

Einen Cache-Key abgleichen

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 es keinen Treffer gibt, wird nach restore-keys und der Version gesucht. Wenn es im aktuellen Branch weiterhin keine Treffer gibt, wiederholt die Aktion cache dieselben Schritte für den Standardbranch. Beachte, dass während der Suche die Bereichseinschränkungen gelten. Weitere Informationen findest du unter Einschränkungen für den Zugriff 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

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. Die Gesamtgröße aller Caches in einem Repository ist jedoch 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 abweisen.

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.

Informationen zum Ändern der Richtlinien für das Größenlimit des Repositorycaches findest du unter Erzwingen von Richtlinien für GitHub Actions in deinem Unternehmen und Verwalten von GitHub Actions-Einstellungen für ein Repository.

Verwalten von Caches

Du kannst die GitHub Enterprise Server-REST-API verwenden, um deine Caches zu verwalten. Derzeit kannst du mithilfe der API deine Cachenutzung anzeigen, wobei in zukünftigen Updates weitere Funktionen erwartet werden. Weitere Informationen findest du in der Dokumentation zur REST-API unter GitHub Actions-Cache.

Du kannst auch eine GitHub CLI-Erweiterung installieren, um deine Caches über die Befehlszeile zu verwalten. Weitere Informationen zur Erweiterung findest du in der Erweiterungsdokumentation. Weitere Informationen zu GitHub CLI-Erweiterungen findest du unter Verwenden von GitHub CLI-Erweiterungen.