# Docker-Layer-Cache in GitHub Actions: warum jeder Build kalt startet und wie die Layer bleiben

> Jeder GitHub-Actions-Job startet auf einer neuen VM ohne Docker-Build-Cache und ohne gezogene Images, und der Standard-Builder von setup-buildx-action startet leer. cache-to und cache-from von buildx (gha, registry, local) holen die Layer als Downloads zurück, innerhalb der 10 GB von GitHub. Ein Runner, der den Build-Cache von Docker auf seiner Festplatte behält, braucht nichts davon, pauschal für $39 im Monat.

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.

- GitHub: eine neue VM pro Job, also keine Layer, keine Images und bei jedem Lauf ein leerer buildx-Builder
- Skipbox: Der Build-Cache und die Images von Docker bleiben auf der Festplatte deiner Maschine, also werden unveränderte Layer weder neu gebaut noch heruntergeladen
- 20.000 Minuten im Monat auf 4 vCPU: $222 bei GitHub, $39 bei Skipbox

**GitHub Actions zum Festpreis, unbegrenzte Minuten** Skipbox führt deine GitHub-Actions-Jobs auf deiner eigenen dedizierten Maschine aus: $39 im Monat, egal wie viele Minuten du nutzt. Docker-Layer und Caches für Abhängigkeiten bleiben zwischen den Jobs erhalten, sodass der nächste Job sofort startet.

Ein Runner mit 4 vCPU, 20.000 Minuten im Monat: GitHub $222 → Skipbox $39. Du sparst jeden Monat $183.

Der Wechsel braucht eine Zeile: `runs-on: skipbox`.

[7-tägige Testphase kostenlos starten](https://app.skipbox.dev/sign-in?ref=g-docker-layer-cache-github-actions-de)

## Warum jeder Build kalt startet

- **Eine neue VM pro Job.** Die [Runner-Referenz](https://docs.github.com/en/actions/reference/runners/github-hosted-runners) 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](https://github.com/docker/setup-buildx-action) erstellt und startet standardmäßig einen Builder mit dem Treiber `docker-container`, und sein `cleanup` (standardmäßig an) entfernt den Builder am Ende des Jobs.
- **14 GB Festplatte.** Das `ubuntu-latest` eines 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](https://docs.docker.com/build/cache/backends/) von Docker und der [Cache-Verwaltung mit GitHub Actions](https://docs.docker.com/build/ci/github-actions/cache/):

| 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`](https://docs.docker.com/build/cache/backends/local/) (ab Buildx 0.35.0); zählt zu den 10 GB |

Welches Backend du auch wählst, [ordne das Dockerfile](https://docs.docker.com/build/cache/optimize/) 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:

```yaml
- 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](https://github.com/reproducible-containers/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 save` in eine tar-Datei schreiben, sie mit actions/cache cachen und im nächsten Job mit `docker load` laden. 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 build` und `docker compose build`** verwenden die Layer des letzten Builds wieder, ohne Änderung am Workflow.
- **Images bleiben auf der Festplatte.** `docker compose up` findet die Images, die es beim letzten Mal gezogen hat; `docker compose pull` holt nur geänderte Layer.
- **Cache-Mounts bleiben** mit dem Build-Cache von Docker, also behält `RUN --mount=type=cache` den 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-from` und `cache-to` kö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.

```yaml
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

1. Melde dich bei Skipbox mit GitHub an.
2. Installiere die GitHub-App von Skipbox und wähle die Repositorys.
3. Ändere `runs-on` und 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](https://docs.skipbox.dev/de/isolation).

## 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 2026-11-19 · https://skipbox.dev/de/guides/docker-layer-cache-github-actions
