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:
| Parameter | Standard | Bedeutung |
|---|---|---|
scope | buildkit | Name des Cache-Objekts. Verwenden Sie pro Image einen eigenen. |
mode | min | min exportiert nur die Layer des finalen Images, max exportiert alle Layer aller Stages. |
ignore-error | false | Der 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?
| Bedarf | Verwenden |
|---|---|
| Einfache, kleine bis mittelgroße Images | type=gha,mode=max mit einem scope |
| Großer Cache, der mit Laptops geteilt wird, oder nicht im GitHub-Cache | type=registry,mode=max |
| Einstufiges Dockerfile, minimale Konfiguration | type=inline |
Volle Kontrolle über actions/cache | type=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:
- Betrachten Sie sie nur als lokale Optimierung und verlassen Sie sich in der CI auf das Layer-Caching.
- Speichern Sie das Mount-Verzeichnis selbst. Werkzeuge von Drittanbietern wie die Action
reproducible-containers/buildkit-cache-dancespeichern und wiederherstellen Cache-Mount-Inhalte überactions/cache. Prüfen Sie diese auf Ihre Sicherheitsanforderungen, bevor Sie sie einsetzen. - 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
- Ordnen Sie das Dockerfile so, dass Abhängigkeits-Layer zuerst kommen (siehe langsame Docker-Builds).
- Halten Sie
.dockerignoreschlank. - Verwenden Sie
--progress=plainoder die Build-Zusammenfassung, um nachCACHED-Zeilen zu suchen. - 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.
Verwandt
- Cargo- und Rust-Builds in GitHub Actions cachenCargo-Registry, Git-Abhängigkeiten und Target-Verzeichnis in GitHub Actions mit Swatinem/rust-cache oder actions/cache cachen, ohne aufgeblähte Caches.
- Go-Module und Build-Cache in GitHub Actions cachenGo-Module (GOMODCACHE) und Build-Cache (GOCACHE) in GitHub Actions mit setup-go oder actions/cache cachen. Keys, go.sum und Cache-Treffer prüfen.
- Gradle-Builds in GitHub Actions cachenGradle-Abhängigkeiten und Build-Cache in GitHub Actions mit gradle/actions/setup-gradle oder actions/cache cachen. Keys, PRs, Bereinigung, Checks.
- npm-Abhängigkeiten in GitHub Actions cachennpm-Abhängigkeiten in GitHub Actions cachen, mit setup-node oder actions/cache. Funktionierendes YAML, der richtige Key, warum nicht node_modules, und Treffer prüfen.