Zum Inhalt springen

GitHub Actions Cache: Limit, Größe und Entfernung

Zuletzt aktualisiert

Das Cache-Limit von GitHub Actions überrascht viele Teams: Ein Repository erhält standardmäßig 10 GB, und sobald der Speicher voll ist, entfernt GitHub ältere Caches. Dadurch können Ihre Builds ohne ersichtlichen Grund wieder langsamer werden. Dieser Leitfaden behandelt Limits, Entfernung, Cache-Größe sowie die Besonderheiten von pnpm und Docker. Für die Grundlagen von actions/cache lesen Sie zuerst den Caching-Leitfaden; dieser hier setzt dort an. Die Angaben unten stammen aus GitHubs Dokumentation zum Dependency-Caching, geprüft am 11.10.2026.

Welche Limits gelten

  • Gesamtgröße pro Repository: standardmäßig 10 GB über alle Caches hinweg. Eigentümer und Administratoren können dieses Limit erhöhen; Speicher über 10 GB wird berechnet.
  • Aufbewahrung: Ein Cache-Eintrag, auf den 7 Tage lang nicht zugegriffen wurde, wird entfernt.
  • Entfernung: Überschreitet das Repository sein Limit, speichert GitHub den neuen Cache trotzdem und entfernt danach Caches (zuerst die am längsten nicht genutzten), bis die Gesamtgröße wieder unter dem Limit liegt.
  • Anzahl der Caches: Die Anzahl ist nicht begrenzt, nur die Gesamtgröße.

Die Cache-Nutzung sehen Sie unter Actions, Seite Caches im Repository sowie mit der CLI: gh cache list --sort size_in_bytes.

Warum Entfernung die CI verlangsamt

Entfernung kann zu Cache-Thrashing führen: Jeder Lauf speichert einen neuen Cache, der einen anderen verdrängt, und dieser fehlt dann beim nächsten Lauf. Anzeichen sind „Cache not found for input keys“ in den Logs bei kürzlich gelaufenen Branches oder eine Trefferquote, die mit wachsendem Team sinkt.

Häufige Ursachen:

  1. Ein neuer Schlüssel pro Commit. Schlüssel wie ${{ github.sha }} erzeugen pro Push einen eigenen Cache. Sie füllen die 10 GB schnell und werden nie getroffen.
  2. Große Caches werden pro Betriebssystem oder Matrix-Zelle dupliziert. 6 Matrix-Zellen mal 700 MB ergeben 4.2 GB.
  3. Caching von node_modules oder Build-Verzeichnissen, die sich bei jeder Änderung am Lockfile ändern, sodass jede Änderung eine weitere vollständige Kopie hinzufügt.
  4. Branch-Beschränkung. Ein Workflow kann Caches wiederherstellen, die auf dem aktuellen Branch, dem Basis-Branch oder dem Standard-Branch erstellt wurden, nicht aber auf parallelen Branches. Caches für Pull Requests werden für den Merge-Ref erstellt, daher ist ein Cache aus einem PR in einem anderen PR nicht sichtbar. Wärmen Sie den Standard-Branch vor, damit alle daraus wiederherstellen können, z. B. mit einem geplanten Job (siehe Cron-Zeitpläne).

Lösungen

Schlüssel, die treffen

- uses: actions/cache@v4
  with:
    path: ~/.cache/pip
    key: pip-${{ runner.os }}-${{ hashFiles('**/requirements*.txt') }}
    restore-keys: |
      pip-${{ runner.os }}-

Bauen Sie den Schlüssel auf das Lockfile statt auf den Commit. Mit restore-keys kann ein Teiltreffer den neuesten ähnlichen Cache wiederherstellen; danach wird unter dem exakten Schlüssel ein neuer Cache gespeichert. Der Cache-Key-Generator erstellt solche Schlüssel.

Weniger speichern, und einmal speichern

  • Cachen Sie nach Möglichkeit den Download-Cache des Paketmanagers statt des installierten Verzeichnisbaums. Er ist kleiner und über Node- oder Python-Versionen hinweg wiederverwendbar.
  • Verwenden Sie in den meisten Jobs actions/cache/restore und in einem Job actions/cache/save (z. B. bei Pushes auf main), sodass PR-Läufe nur lesen und nicht jeweils neue Einträge schreiben.
  • Löschen Sie veraltete Caches beim Schließen eines PRs mit gh cache delete, um Platz für den Standard-Branch zu schaffen.
- uses: actions/cache/restore@v4
  with: { path: ~/.cache/pip, key: pip-${{ hashFiles('requirements.txt') }} }

Cache-Größe vor dem Speichern prüfen

Große Einträge sind langsam beim Speichern und Wiederherstellen. Dauert das Wiederherstellen länger als die Installation, die es ersetzt, sollten Sie den Cache entfernen. Eine Wiederherstellung von 1.5 GB über das Netzwerk kann länger dauern als eine schnelle Paketinstallation, was ein häufiger Grund für „GitHub Actions Cache langsam“ ist.

Hinweise zu Cache v4

actions/cache@v4 nutzt den neueren Cache-Dienst von GitHub. GitHub hat die älteren Action-Versionen, die das alte Cache-Backend nutzten, abgekündigt, daher können alte Pins fehlschlagen. Verwendet Ihr Workflow eine davon, aktualisieren Sie auf @v4. v4 stellt außerdem cache-hit als Output bereit: true nur bei einem exakten Schlüsseltreffer, sodass Sie Schritte wie npm ci überspringen können, wenn Sie node_modules cachen. Die aktuellen Eingaben finden Sie in der README der Action.

Besonderheiten von pnpm

pnpm verwaltet einen inhaltsadressierten Store und verlinkt Dateien hart in node_modules. Cachen Sie den Store, nicht node_modules:

- uses: pnpm/action-setup@v4
- uses: actions/setup-node@v4
  with:
    node-version: 22
    cache: pnpm
- run: pnpm install --frozen-lockfile

setup-node mit cache: pnpm cacht den Store anhand von pnpm-lock.yaml. Beim manuellen Cachen ermitteln Sie den Pfad mit pnpm store path. Das Wiederherstellen des Stores und das Ausführen von pnpm install --frozen-lockfile --prefer-offline ist in der Regel schnell, weil nur Dateien verlinkt werden. In einem Monorepo ergibt ein Lockfile einen Schlüssel, was die Anzahl der Caches gering hält.

Docker-Image-Caching

Das Cachen von Docker-Layern mit actions/cache kann viele Gigabyte belegen und das 10-GB-Limit erreichen. Optionen:

  • type=gha-Cache in Buildx speichert Layer im selben Cache-Dienst und zählt gegen dasselbe Limit. Verwenden Sie mode=min, um nur die finalen Image-Layer zu speichern statt mode=max, falls die Größe ein Problem ist.
  • Ein Registry-Cache (type=registry) speichert Layer stattdessen in Ihrer Container-Registry, außerhalb des 10-GB-Limits.
  • Ordnen Sie das Dockerfile so an, dass Abhängigkeits-Layer vor dem Kopieren des Quellcodes stehen, damit sich die aufwendigen Layer selten ändern.
- uses: docker/build-push-action@v6
  with:
    cache-from: type=gha
    cache-to: type=gha,mode=min

Weitere Optionen finden Sie unter Docker-Layer-Caching in der CI.

Kostet Cache-Speicher Geld?

Innerhalb des Standardlimits fallen keine zusätzlichen Kosten an. Eine Erhöhung über 10 GB wird für den zusätzlich genutzten Speicher berechnet. Die übrigen Posten erklärt GitHub Actions Preise erklärt, und den Kostenrechner finden Sie dort ebenfalls.

Wann Caches nicht die Lösung sind

Sind Caches groß und die Wiederherstellung langsam, hilft oft ein Runner mit lokalem persistentem Speicher oder schnellerem Netzwerk mehr als das Anpassen der Schlüssel. Vergleichen Sie unter schnellere GitHub Actions Runner. Weitere Lösungen bieten der Leitfaden zur Beschleunigung und der Hub für langsame CI.

FAQ

Wie groß ist das Cache-Limit bei GitHub Actions?

Standardmäßig 10 GB pro Repository für alle Caches zusammen. Administratoren können diesen Wert erhöhen, Nutzung über 10 GB wird berechnet.

Wie lange bewahrt GitHub einen Cache auf?

Einträge, die 7 Tage lang nicht abgerufen wurden, werden entfernt. Außerdem werden Einträge gelöscht, wenn das Repository sein Größenlimit überschreitet.

Warum wird mein GitHub Actions Cache nicht wiederhergestellt?

Prüfen Sie, ob der Schlüssel übereinstimmt, ob der Cache auf einem Branch erstellt wurde, auf den Sie Lesezugriff haben, ob er nicht entfernt wurde und ob Sie actions/cache@v4 verwenden.

Sollte ich pnpm node_modules cachen?

Cachen Sie stattdessen den pnpm-Store, indem Sie setup-node mit cache: pnpm verwenden.

Diesen Workflow auf compiler.dev ausführen Keine Karte nötig · 200 kostenlose Minuten

Kostenlos testen