Abhängigkeiten zwischenspeichern um Workflows zu beschleunigen

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.

Aufträge für GitHub-gehostete Runner beginnen in einem sauberen Runner-Image und müssen Abhängigkeiten jedes Mal herunterladen. Dies führt zu erhöhter Netzwerkauslastung, längerer Laufzeit und erhöhten Kosten. 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.

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 Artefakten von Workflowausführungen findest du unter Speichern und Freigeben von Daten aus einem Workflow.

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-
  

• 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@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

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@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 Zugreifen auf kontextbezogene Informationen zu Workflowausführungen und unter 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

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 auf 10 GB. Sobald ein Repository seinen maximalen Cachespeicher erreicht hat, wird durch die Cacheentfernungsrichtlinie Speicherplatz geschaffen, indem die ältesten Caches im Repository gelöscht werden.

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.

Verwalten von Caches

Zum Verwalten der über deine Workflows erstellten Caches kannst du folgende Aufgaben ausführen:

• Anzeigen einer Liste aller Cacheeinträge für ein Repository
• Filtern und Sortieren der Liste der Caches anhand bestimmter Metadaten, z. B. Cachegröße, Erstellungszeitpunkt oder Zeitpunkt des letzten Zugriffs
• Löschen von Cacheeinträgen aus einem Repository
• Überwachen der aggregierten Cachenutzung für Repositorys und Organisationen

Es gibt mehrere Möglichkeiten, die Caches für deine Repositorys zu verwalten:

• Verwenden der GitHub-Weboberfläche, wie unten gezeigt.

• Verwendung der REST-API. Weitere Informationen findest du unter REST-API-Endpunkte für GitHub-Actions-Cache.

• Installieren des gh cache-Unterbefehls zum Verwalten Ihrer Caches über die Befehlszeile. Weitere Informationen finden Sie in der Dokumentation zur GitHub-CLI.

  Note

  Stelle bei manueller Ausführung sicher, dass Version 2.32.0 oder höher der CLI installiert ist.

Anzeigen von Cacheeinträgen

Du kannst die Weboberfläche verwenden, um eine Liste der Cacheeinträge für ein Repository anzuzeigen. In der Cacheliste kannst du sehen, wie viel Speicherplatz jeder Cache verbraucht, wann der Cache erstellt und wann er zuletzt verwendet wurde.

1. Navigieren Sie auf GitHub zur Hauptseite des Repositorys.

2. Klicke unter dem Namen deines Repositorys auf Aktionen.

   

3. Klicke auf der linken Seitenleiste unter dem Abschnitt „Verwaltung“ auf Caches.

4. Überprüfe die Liste der Cacheeinträge für das Repository.

   • Um nach Cacheeinträgen zu suchen, die für einen bestimmten Branch verwendet werden, klicke auf das Dropdownmenü Branch, und wähle einen Branch aus. In der Cacheliste werden alle Caches angezeigt, die für den ausgewählten Branch verwendet werden.
   • Um nach Cacheeinträgen mit einem bestimmten Cacheschlüssel zu suchen, verwende die Syntax key: key-name im Feld Caches filtern. In der Cacheliste werden Caches aus allen Branches angezeigt, in denen der Schlüssel verwendet wurde.
   

Löschen von Cacheeinträgen

Benutzer mit write-Zugriff auf ein Repository können die GitHub-Weboberfläche verwenden, um Cacheeinträge zu löschen.

1. Navigieren Sie auf GitHub zur Hauptseite des Repositorys.

2. Klicke unter dem Namen deines Repositorys auf Aktionen.

   

3. Klicke auf der linken Seitenleiste unter dem Abschnitt „Verwaltung“ auf Caches.

4. Klicke rechts neben dem Cacheeintrag, den du löschen möchtest, auf .

   

Erzwingen des Löschens von Cacheeinträgen

Caches verfügen über Branchumfangseinschränkungen. Das bedeutet, dass einige Caches eingeschränkte Nutzungsoptionen besitzen. Weitere Informationen zu Cache-Umfangseinschränkungen findest du unter Einschränkungen für den Zugriff auf einen Cache weiter oben in diesem Artikel. Wenn auf einen bestimmten Branch begrenzte Caches ein hohes Speicherkontingent verbrauchen, kann dies dazu führen, dass Caches aus dem Branch default häufig erstellt und gelöscht werden.

In einem Repository könnten beispielsweise viele neue Pull Requests geöffnet werden, die jeweils über eigene Caches verfügen, die auf diesen Branch beschränkt sind. Diese Caches könnten den Großteil des Cachespeichers dieses Repository belegen. Sobald ein Repository seinen maximalen Cachespeicher erreicht hat, wird durch die Cacheentfernungsrichtlinie Speicherplatz geschaffen, indem die ältesten Caches im Repository gelöscht werden. Um in diesem Fall ein Cache-Thrashing zu verhindern, kannst du Workflows einrichten, mit denen Caches schneller gelöscht werden als über die Richtlinie zur Cacheentleerung. Du kannst GitHub CLI verwenden, um Caches für bestimmte Branches zu löschen.

Im folgenden Beispielworkflow wird gh cache zum Löschen von bis zu 100 von einem Branch erstellten Caches verwendet, sobald ein Pull Request geschlossen wird.

Sie können den Workflow mit dem Ereignis pull_request_target auslösen, um das folgende Beispiel für repositoryübergreifende Pull Requests oder für Pull Requests von Forks auszuführen. Wenn Sie den Workflow mit pull_request_target auslösen, sollten Sie die entsprechenden Sicherheitsaspekte berücksichtigen. Weitere Informationen findest du unter Ereignisse zum Auslösen von Workflows.

name: cleanup caches by a branch
on:
  pull_request:
    types:
      - closed

jobs:
  cleanup:
    runs-on: ubuntu-latest
    steps:
      - name: Cleanup
        run: |
          echo "Fetching list of cache key"
          cacheKeysForPR=$(gh cache list --ref $BRANCH --limit 100 --json id --jq '.[].id')

          ## Setting this to not fail the workflow while deleting cache keys.
          set +e
          echo "Deleting caches..."
          for cacheKey in $cacheKeysForPR
          do
              gh cache delete $cacheKey
          done
          echo "Done"
        env:
          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
          GH_REPO: ${{ github.repository }}
          BRANCH: refs/pull/${{ github.event.pull_request.number }}/merge

Alternativ kannst du die API verwenden, um alle Caches automatisch in einem eigenen Intervall aufzulisten oder zu löschen. Weitere Informationen findest du unter REST-API-Endpunkte für GitHub-Actions-Cache.