Docker-Layer-Cache in GitHub Actions: warum jeder Build kalt startet und wie die Layer bleiben
Der Layer-Cache von Docker geht bei jedem GitHub-Actions-Lauf verloren, weil jeder Job auf einem von GitHub gehosteten Runner auf einer neuen VM startet: kein Build-Cache, keine gezogenen Images. Auch der Standard-Builder von docker/setup-buildx-action (docker-container) startet in jedem Job leer und wird an dessen Ende entfernt. Die übliche Lösung ist, den Cache mit buildx zu exportieren. cache-to: type=gha,mode=max und cache-from: type=gha halten die Layer im Actions-Cache von GitHub, 10 GB pro Repository und geteilt mit jedem anderen Cache; type=registry hält sie in deiner Registry; type=local in einem Verzeichnis, das du mit actions/cache sicherst. Jede dieser Varianten macht aus einem Neubau bei jedem Lauf einen Upload und einen Download.
Skipbox behält die Layer dort, wo der Build läuft. Deine Jobs laufen auf der dedizierten Maschine deines Kontos, die die Images, Layer und den Build-Cache von Docker zwischen den Jobs behält, auf einer Festplatte mit 80 GB bei S gegenüber 14 GB auf dem Runner von GitHub. docker build und docker compose build verwenden die Layer des letzten Builds wieder, und Images, die compose gezogen hat, liegen schon auf der Festplatte. setup-buildx-action funktioniert unverändert, und sein Builder findet diese Layer ebenfalls. Ändere eine Zeile, runs-on: skipbox, pauschal für $39 im Monat mit unbegrenzten Minuten.
Warum jeder Build kalt startet
- Eine neue VM pro Job. Die Runner-Referenz von GitHub: „each GitHub-hosted runner is a new virtual machine (VM) hosted by GitHub.“ Jeder von GitHub gehostete Runner ist also eine neue VM. Nichts, was der letzte Job gebaut oder gezogen hat, ist darauf.
- Ein leerer Builder. docker/setup-buildx-action erstellt und startet standardmäßig einen Builder mit dem Treiber
docker-container, und seincleanup(standardmäßig an) entfernt den Builder am Ende des Jobs. - 14 GB Festplatte. Das
ubuntu-latesteines privaten Repositorys hat 2 CPUs, 8 GB und 14 GB SSD. Ein großes Image, sein Build-Cache und ein Cache-Archiv zum Entpacken können den Platz sprengen („no space left on device“).
Die Cache-Backends von buildx und was jedes kostet
Aus den Cache-Backends von Docker und der Cache-Verwaltung mit GitHub Actions:
| Backend | Wohin die Layer gehen | Was jeder Lauf bezahlt | Grenzen |
|---|---|---|---|
type=gha | Der Actions-Cache von GitHub | Lädt neue Layer hoch, lädt die benötigten herunter | 10 GB pro Repository mit jedem anderen Cache, die ältesten werden zuerst verdrängt; der Standard-scope buildkit wird von jedem Build überschrieben; die Cache-API von GitHub drosselt |
type=registry | Ein separates Cache-Image in deiner Registry | Zieht den Cache aus der Registry, pusht den neuen | Ein Registry-Login mit Push-Rechten; Speicher und Traffic der Registry |
type=inline | Im Image selbst | Zieht das Image, um seinen Cache zu lesen | Nur mode=min: Layer von Zwischen-Stages werden nicht behalten |
type=local + actions/cache | Ein mit actions/cache gesichertes Verzeichnis | Lädt das ganze Verzeichnis herunter, entpackt es und lädt es dann hoch | Wächst mit jedem Lauf, außer mit reset=true (ab Buildx 0.35.0); zählt zu den 10 GB |
Welches Backend du auch wählst, ordne das Dockerfile so, dass die Layer, die sich am seltensten ändern, zuerst kommen: Kopiere das Lockfile und installiere die Abhängigkeiten, bevor du den Quellcode kopierst. Sonst macht jeder Commit den Installations-Layer ungültig, und kein Cache bringt ihn zurück.
mode=min, der Standard, behält nur die Layer des fertigen Images. mode=max behält die Layer jeder Stage, also trifft ein Multi-Stage-Build öfter und lädt mehr hoch.
Ein typisches Setup mit type=gha, mit eigenem scope pro Image:
- uses: docker/setup-buildx-action@v4
- uses: docker/build-push-action@v7
with:
context: .
tags: app:ci
load: true
cache-from: type=gha,scope=app
cache-to: type=gha,scope=app,mode=max
Cache-Mounts überleben nicht. RUN --mount=type=cache (der Cache eines Paketmanagers im Build) wird standardmäßig nicht im GitHub-Actions-Cache behalten; die Doku von Docker verweist auf buildkit-cache-dance, um ihn in actions/cache hinein und wieder heraus zu bewegen, ein weiterer Download und Upload pro Lauf.
docker compose zieht jedes Image in jedem Job
Integrationstests, die Postgres, Redis und ein paar Dienste mit docker compose up starten, ziehen in jedem Job jedes Image, weil die VM neu ist. Auf von GitHub gehosteten Runnern verschieben die Optionen nur den Download:
- Die Images mit
docker savein eine tar-Datei schreiben, sie mit actions/cache cachen und im nächsten Job mitdocker loadladen. Das zählt zu den 10 GB, und das Laden kostet eigene Zeit. - Die Service-Images mit buildx und einem der Cache-Backends oben bauen, wobei die Basis-Images trotzdem gezogen werden müssen.
Wenn die Lösung eine Maschine ist, die den Cache von Docker behält
Jedes Backend oben gibt es nur, weil der Builder vergisst. Ein Docker-Daemon, der zwischen den Jobs bestehen bleibt, hat die Layer des letzten Builds, seine Cache-Mounts und jedes gezogene Image schon auf seiner eigenen Festplatte. Es gibt nichts zu exportieren, nichts zu importieren und keine 10 GB zu teilen.
Skipbox behält den Cache von Docker auf deiner Maschine
Zu jedem Tarif gehört die dedizierte Maschine deines Kontos, die zwischen den Jobs bestehen bleibt:
docker buildunddocker compose buildverwenden die Layer des letzten Builds wieder, ohne Änderung am Workflow.- Images bleiben auf der Festplatte.
docker compose upfindet die Images, die es beim letzten Mal gezogen hat;docker compose pullholt nur geänderte Layer. - Cache-Mounts bleiben mit dem Build-Cache von Docker, also behält
RUN --mount=type=cacheden Cache des Paketmanagers ohne zusätzlichen Step. - docker/setup-buildx-action funktioniert unverändert. Sein Builder startet mit den Layern, die der letzte Build deines Repositorys auf der Maschine hinterlassen hat, und
cache-fromundcache-tokönnen weg. In unserem eigenen Lauf der CI eines öffentlichen Projekts auf einer Maschine mit 4 vCPU (19. November 2026, je ein Lauf) dauerte der Step für den Image-Build beim ersten Lauf 177 s und bei der Wiederholung 4 s, mit 31 Steps als CACHED. - Festplatte: Gelöscht wird erst, wenn die Festplatte nach einem Job fast voll ist. Dann gehen zuerst verwaiste Images, danach der am längsten ungenutzte Build-Cache.
jobs:
build:
runs-on: skipbox # was ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: docker/setup-buildx-action@v4
- uses: docker/build-push-action@v7
with:
context: .
tags: app:ci
load: true
Ein Job wählt seine Größe per Label:
| Label | Maschine | Festplatte | Tarif |
|---|---|---|---|
skipbox | 4 vCPU · 16 GB | 80 GB | S, $39 im Monat |
skipbox-8x16 | 8 vCPU · 16 GB | 160 GB | M, $79 im Monat |
skipbox-16x32 | 16 vCPU · 32 GB | 320 GB | L, $149 im Monat |
Die Minuten sind unbegrenzt. Bei 20.000 Minuten im Monat auf 4 vCPU berechnet GitHub $222; Skipbox S kostet $39, $183 weniger.
Der Wechsel ist eine Zeile
- Melde dich bei Skipbox mit GitHub an.
- Installiere die GitHub-App von Skipbox und wähle die Repositorys.
- Ändere
runs-onund pushe.
Der erste Job baut jeden Layer. Der zweite findet sie auf der Maschine.
Sicherheit
- Die Maschine gehört nur deinem Konto. Keine Jobs eines anderen Unternehmens laufen darauf.
- Nach jedem Job werden die Zugangsdaten, Prozesse und Container des Runners gelöscht, ebenso
~/.docker/config.json, also wandert ein Registry-Login nicht in den nächsten Job. „Frische VM für jeden Job“ gibt stattdessen jedem Job eine frische Maschine. - Code von Personen ohne Schreibzugriff (etwa Pull Requests aus Forks) läuft auf einer frischen Wegwerf-Maschine, nie auf deiner.
Die Einzelheiten stehen unter Wie Jobs isoliert werden.
Probier es mit deinem Docker-Build
Die Testphase ist kostenlos für 7 Tage oder 3.000 Job-Minuten, je nachdem, was zuerst erreicht ist, und braucht keine Karte. Verschieb deinen Docker-Build auf runs-on: skipbox, führe ihn zweimal aus und leg den Build-Step des zweiten Laufs neben den von GitHub.
FAQ
Warum geht der Docker-Layer-Cache bei jedem GitHub-Actions-Lauf verloren?
Weil jeder Job auf einem von GitHub gehosteten Runner auf einer neuen VM startet, ohne Build-Cache und ohne Images vom letzten Lauf. docker/setup-buildx-action kommt noch dazu: Standardmäßig erstellt es einen docker-container-Builder, der leer startet und am Ende des Jobs entfernt wird. Also wird jeder Layer neu gebaut, außer du exportierst den Cache mit cache-to und importierst ihn mit cache-from oder lässt den Job auf einer Maschine laufen, die den Build-Cache von Docker behält.
Wie cache ich Docker-Layer in GitHub Actions?
Auf von GitHub gehosteten Runnern mit den Cache-Exportern von buildx: cache-from: type=gha und cache-to: type=gha,mode=max in docker/build-push-action speichern die Layer im Actions-Cache von GitHub (10 GB pro Repository, geteilt mit jedem anderen Cache). type=registry speichert sie als separates Image in deiner Registry, type=local in einem Verzeichnis, das du mit actions/cache sicherst. Gib bei type=gha jedem Image einen eigenen scope, denn der Standard-scope wird von jedem Build überschrieben. Auf einer Maschine, die ihre Festplatte behält, verwendet docker build die Layer ohne Exporter wieder.
Warum ist buildx mit cache-to type=gha trotzdem langsam?
Weil die Layer weiterhin wandern. Mit mode=max lädt jeder Lauf jeden neuen Layer jeder Stage hoch, und ein späterer Lauf lädt die Layer herunter, die er braucht. Der Cache teilt sich die 10 GB pro Repository bei GitHub mit allem anderen, also wird er verdrängt, und die Cache-API von GitHub drosselt einen Build, der zu viele Anfragen stellt. Ein Builder, der die Layer schon auf seiner Festplatte hat, spart beide Richtungen.
Wie verhindere ich, dass docker compose in jedem Job dieselben Images zieht?
Auf einem von GitHub gehosteten Runner gar nicht, du kannst nur den Download verschieben: Die Images mit docker save in eine tar-Datei schreiben, sie mit actions/cache cachen und im nächsten Job mit docker load laden. Das zählt zu denselben 10 GB und ist bei jedem Lauf ein Download und ein Laden. Auf einer Maschine, die ihre Festplatte behält, sind die Images, die compose beim letzten Mal gezogen hat, schon da, und docker compose pull holt nur geänderte Layer.
Muss ich meinen Workflow ändern, damit Skipbox den Cache von Docker behält?
Nur runs-on: Die Maschine deines Kontos behält die Images, Layer und den Build-Cache von Docker zwischen den Jobs. docker build und docker compose build verwenden sie wieder, und docker/setup-buildx-action funktioniert unverändert: Sein Builder startet mit den Layern, die der letzte Build deines Repositorys auf der Maschine hinterlassen hat. cache-from und cache-to können weg.
Was kostet es, das auszuprobieren?
Nichts. Die Testphase dauert 7 Tage oder 3.000 Job-Minuten, je nachdem, was zuerst erreicht ist, ohne Karte. Verschieb deinen Docker-Build auf runs-on: skipbox, führe ihn zweimal aus und vergleiche den Build-Step des zweiten Laufs mit dem von GitHub.
Aktualisiert am 19. November 2026