Zum Inhalt springen

Docker-Buildx-Cache in GitHub Actions: gha, registry

Zuletzt aktualisiert am

Um Docker-Builds in GitHub Actions zu cachen, verwenden Sie docker/setup-buildx-action und docker/build-push-action mit cache-from: type=gha und cache-to: type=gha,mode=max. Damit wird der Layer-Cache von BuildKit im GitHub-Actions-Cache gespeichert. Es gibt vier Backends (gha, registry, inline, local). Dieser Leitfaden zeigt jedes davon, wann Sie es wählen sollten und welche Grenzen gelten.

Wenn Ihr Build langsam ist und Sie nicht wissen, warum, beginnen Sie mit Docker-Build in CI zu langsam. Die Konzepte erklärt Docker-Layer-Caching in CI.

Die Standardkonfiguration: type=gha

name: Docker
on:
  push:
    branches: [main]
  pull_request:

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v6
      - uses: docker/setup-buildx-action@v3
      - uses: docker/build-push-action@v7
        with:
          context: .
          push: false
          tags: app:ci
          cache-from: type=gha
          cache-to: type=gha,mode=max

Die Einrichtung von Buildx ist erforderlich. Laut Docker-Dokumentation (Stand Oktober 2026) funktioniert der Standardtreiber docker mit dem Backend gha nur, wenn der containerd-Image-Store aktiviert ist. Andernfalls benötigen Sie einen anderen Treiber, den setup-buildx-action erstellt. Cache-URL und Token werden innerhalb eines Workflows automatisch gesetzt.

Wichtige Parameter

Aus der Dokumentation des Docker-Backends gha:

ParameterStandardBedeutung
scopebuildkitName des Cache-Objekts. Verwenden Sie pro Image einen eigenen.
modeminmin exportiert nur die Layer des finalen Images, max exportiert alle Layer aller Stages.
ignore-errorfalseDer Build schlägt nicht fehl, wenn das Exportieren des Caches scheitert.

Verwenden Sie mode=max bei Multi-Stage-Builds. Bei min sind Zwischen-Stages (etwa die Installation der Abhängigkeiten oder der Kompilierschritt) nicht im Cache, und genau diese sind teuer. max speichert sie, dafür wird der Cache größer.

Legen Sie pro Image einen Scope fest. Der Standard-Scope ist geteilt, daher überschreiben sich zwei Images, die im selben Repository gebaut werden, gegenseitig den Cache:

cache-from: type=gha,scope=web
cache-to: type=gha,scope=web,mode=max

Bei einer Matrix nehmen Sie den Matrixwert in den Scope auf, zum Beispiel scope=build-${{ matrix.platform }}.

Die Dokumentation beschreibt außerdem eine neuere Cache-Service-API (v2), die über die URL oder eine Einstellung version ausgewählt wird. Wenn nach einer Änderung auf GitHub-Seite Cache-Fehler auftreten, prüfen Sie, ob Ihre Buildx- und BuildKit-Versionen aktuell sind, denn ältere Versionen sprechen die alte API an.

Drosselung

Intensiver Cache-Export kann API-Ratenlimits auslösen. Die Build-Action übergibt github-token (Standard secrets.GITHUB_TOKEN) an Buildx, um Drosselung zu vermeiden. Lassen Sie diesen Wert gesetzt.

Grenzen von type=gha

  • Er liegt im GitHub Actions Cache und teilt sich daher das Kontingent von 10 GB pro Repository mit npm, pip und allem anderen. Ein mode=max-Docker-Cache kann allein schon einige GB belegen.
  • Einträge, die 7 Tage nicht genutzt wurden, werden entfernt. Ist das Repository über dem Kontingent, fliegen zuerst die zuletzt genutzten Einträge. Siehe Cache-Limits.
  • PRs lesen den Cache des Basis-Branches und schreiben eigene, gescopte Einträge. Bauen Sie auch auf main, damit der Basis-Cache warm bleibt.
  • Self-Hosted-Runner haben je nach Setup möglicherweise keinen Zugriff auf den GitHub-Cache-Dienst. Prüfen Sie das, bevor Sie sich darauf verlassen. Ein Registry-Cache umgeht die Frage.

type=registry

Speichern Sie den Cache als Image in einer Container-Registry:

- uses: docker/login-action@v3
  with:
    registry: ghcr.io
    username: ${{ github.actor }}
    password: ${{ secrets.GITHUB_TOKEN }}
- uses: docker/build-push-action@v7
  with:
    context: .
    push: true
    tags: ghcr.io/${{ github.repository }}:latest
    cache-from: type=registry,ref=ghcr.io/${{ github.repository }}:buildcache
    cache-to: type=registry,ref=ghcr.io/${{ github.repository }}:buildcache,mode=max

Verwenden Sie dies, wenn der Cache groß ist, wenn Runner nicht im Cache-Netzwerk von GitHub liegen oder wenn lokale Entwickler und CI einen Cache teilen sollen. Er wird nicht auf das Kontingent von 10 GB für Actions angerechnet, stattdessen gelten die Regeln für den Registry-Speicher. Das Hochladen und Herunterladen eines großen Caches kostet Zeit, halten Sie die Registry daher nah am Runner. Manche Registries unterstützen keine Cache-Manifeste. Prüfen Sie, ob Ihre es tut.

type=inline

Bettet Cache-Metadaten in das Image ein, das Sie hochladen, sodass cache-from das Image selbst nutzen kann:

cache-from: type=registry,ref=ghcr.io/org/app:latest
cache-to: type=inline

Das ist die einfachste Option und braucht kein zusätzliches Tag. Der Nachteil: Nur mode=min wird unterstützt, Zwischen-Stages eines Multi-Stage-Builds werden also nicht gecacht. Für ein einstufiges Dockerfile ist das in Ordnung, bei mehrstufigen Builds schwach.

type=local

Schreibt den Cache in ein Verzeichnis, das Sie mit actions/cache speichern:

- uses: actions/cache@v6
  with:
    path: /tmp/.buildx-cache
    key: buildx-${{ runner.os }}-${{ github.sha }}
    restore-keys: |
      buildx-${{ runner.os }}-
- uses: docker/build-push-action@v7
  with:
    context: .
    cache-from: type=local,src=/tmp/.buildx-cache
    cache-to: type=local,dest=/tmp/.buildx-cache-new,mode=max

Dies ist das veraltete Muster. Es schrumpft nie von selbst, weil jeder Export das Verzeichnis erweitert. Daher fügen Leute einen Schritt hinzu, der -new über das alte Verzeichnis verschiebt. type=gha ersetzt es in den meisten Fällen. Verwenden Sie local, wenn Sie einen Cache brauchen, den Sie vollständig über Schlüssel von actions/cache steuern.

Welches Backend?

BedarfVerwenden
Einfache, kleine bis mittelgroße Imagestype=gha,mode=max mit einem scope
Großer Cache, der mit Laptops geteilt wird, oder nicht im GitHub-Cachetype=registry,mode=max
Einstufiges Dockerfile, minimale Konfigurationtype=inline
Volle Kontrolle über actions/cachetype=local

Cache-Mounts und warum sie auf frischen Runnern verloren gehen

RUN --mount=type=cache,target=/root/.cache/pip pip install -r requirements.txt gibt einem Build-Schritt ein persistentes Verzeichnis, sodass pip nicht bei jedem erneuten Ausführen der Layer alles neu herunterlädt. Das ist ein großartiges Feature auf Ihrem Laptop oder auf einem langlebigen Builder.

Auf GitHub-gehosteten Runnern bringt es standardmäßig nichts. Ein Cache-Mount liegt im lokalen BuildKit-Status auf dem Builder, nicht im Layer-Cache, den cache-to exportiert. Ein frischer Runner bedeutet ein frisches BuildKit, daher ist der Mount bei jedem Job leer. type=gha und type=registry exportieren Layer, keine Mounts.

Optionen, wenn Sie auf Cache-Mounts setzen:

  1. Betrachten Sie sie nur als lokale Optimierung und verlassen Sie sich in der CI auf das Layer-Caching.
  2. Speichern Sie das Mount-Verzeichnis selbst. Werkzeuge von Drittanbietern wie die Action reproducible-containers/buildkit-cache-dance speichern und wiederherstellen Cache-Mount-Inhalte über actions/cache. Prüfen Sie diese auf Ihre Sicherheitsanforderungen, bevor Sie sie einsetzen.
  3. Verwenden Sie einen persistenten Builder. Dedizierte Build-Services behalten den BuildKit-Status zwischen Läufen. Depot macht das für Docker-Builds; siehe den Depot-Vergleich. Ein selbst gehosteter Runner mit persistenter Festplatte kann ebenfalls funktionieren.

Den Cache-Treffer erzielen

  1. Ordnen Sie das Dockerfile so, dass Abhängigkeits-Layer zuerst kommen (siehe langsame Docker-Builds).
  2. Halten Sie .dockerignore schlank.
  3. Verwenden Sie --progress=plain oder die Build-Zusammenfassung, um nach CACHED-Zeilen zu suchen.
  4. Bauen Sie auf main, damit Branches eine Basis zum Lesen haben.

compiler.dev behält einen Docker-Layer-Cache auf der Maschine zwischen den Jobs, sodass ein einfaches docker build Layer wiederverwenden kann, ohne sie zu exportieren. Wechseln Sie mit runs-on: [self-hosted, Linux, compiler-ci]; siehe Preise.

FAQ

Sollte ich mode=max oder mode=min verwenden?

max für mehrstufige Builds, da hier auch Zwischenstufen gecacht werden. min ist kleiner und für einstufige Images ausreichend.

Warum überschreiben sich zwei Images gegenseitig den Cache?

Sie teilen sich den Standard-scope buildkit. Geben Sie jedem einen eindeutigen scope.

Kann ich type=gha auf selbst gehosteten Runnern verwenden?

Das hängt davon ab, ob der Runner den Cache-Dienst von GitHub erreichen kann. Testen Sie mit einem kleinen Build oder verwenden Sie einen Registry-Cache.

Zählt der gha-Cache auf mein 10-GB-Limit?

Ja. Er wird im selben Actions-Cache gespeichert.

Benötige ich setup-buildx-action?

Für type=gha und die meisten Backends ja. Der Standard-Treiber unterstützt sie ohne den containerd-Image-Store nicht.

Führen Sie diesen Docker-Build auf compiler.dev aus Keine Karte nötig · 200 kostenlose Minuten

Kostenlos testen