# Cache dei layer Docker in GitHub Actions: perché ogni build parte a freddo, e come conservare i layer

> Ogni job di GitHub Actions parte su una VM nuova senza cache di build Docker né immagini scaricate, e il builder predefinito di setup-buildx-action parte vuoto. cache-to e cache-from di buildx (gha, registry, local) riportano i layer come download, dentro i 10 GB di GitHub. Un runner che tiene la cache di build di Docker sul suo disco non ne ha bisogno, a un prezzo fisso di $39 al mese.

La cache dei layer di Docker si perde a ogni esecuzione di GitHub Actions perché ogni job su un runner ospitato da GitHub parte su una VM nuova: nessuna cache di build, nessuna immagine scaricata. Anche il builder predefinito di docker/setup-buildx-action (`docker-container`) parte vuoto in ogni job e viene rimosso alla fine. La soluzione abituale è esportare la cache con buildx. `cache-to: type=gha,mode=max` e `cache-from: type=gha` tengono i layer nella cache di Actions di GitHub, 10 GB per repository condivisi con ogni altra cache; `type=registry` li tiene nel tuo registry; `type=local` in una cartella che salvi con actions/cache. Ognuno trasforma una ricostruzione in un upload e un download a ogni esecuzione.

Skipbox tiene i layer dove gira la build. I tuoi job girano sulla macchina del tuo account, che conserva immagini, layer e cache di build di Docker tra un job e l'altro, su un disco da 80 GB su S contro i 14 GB del runner di GitHub. `docker build` e `docker compose build` riusano i layer dell'ultima build, e le immagini scaricate da compose sono già sul disco. setup-buildx-action funziona così com'è, e anche il suo builder trova quei layer. Cambi una riga, `runs-on: skipbox`, a un prezzo fisso di $39 al mese con minuti illimitati.

- GitHub: una VM nuova per job, quindi niente layer, niente immagini e un builder buildx vuoto a ogni esecuzione
- Skipbox: la cache di build e le immagini di Docker restano sul disco della tua macchina, quindi i layer invariati non si ricostruiscono né si scaricano
- 20.000 minuti al mese su 4 vCPU: $222 su GitHub, $39 su Skipbox

**GitHub Actions a prezzo fisso, minuti illimitati** Skipbox esegue i tuoi job di GitHub Actions su una macchina dedicata tutta tua: $39 al mese, per quanti minuti tu esegua. I layer Docker e le cache delle dipendenze restano tra un job e l'altro, così il job successivo parte subito.

Un runner da 4 vCPU, 20.000 minuti al mese: GitHub $222 → Skipbox $39. Risparmi $183 ogni mese.

Per passare basta una riga: `runs-on: skipbox`.

[Inizia la prova gratuita di 7 giorni](https://app.skipbox.dev/sign-in?ref=g-docker-layer-cache-github-actions-it)

## Perché ogni build parte a freddo

- **Una VM nuova per job.** Il [riferimento dei runner](https://docs.github.com/en/actions/reference/runners/github-hosted-runners) di GitHub: "each GitHub-hosted runner is a new virtual machine (VM) hosted by GitHub." Niente di quello che l'ultimo job ha costruito o scaricato è lì.
- **Un builder vuoto.** [docker/setup-buildx-action](https://github.com/docker/setup-buildx-action) crea e avvia di default un builder con il driver `docker-container`, e il suo `cleanup` (attivo di default) rimuove il builder alla fine del job.
- **14 GB di disco.** L'`ubuntu-latest` di un repository privato ha 2 CPU, 8 GB e 14 GB di SSD. Un'immagine grande, la sua cache di build e un archivio di cache da scompattare possono finire lo spazio ("no space left on device").

## I backend di cache di buildx, e quanto costa ciascuno

Dai [backend di cache](https://docs.docker.com/build/cache/backends/) di Docker e dalla [gestione della cache con GitHub Actions](https://docs.docker.com/build/ci/github-actions/cache/):

| Backend | Dove vanno i layer | Cosa paga ogni esecuzione | Limiti |
|---|---|---|---|
| `type=gha` | La cache di Actions di GitHub | Carica i layer nuovi, scarica quelli che le servono | 10 GB per repository insieme a ogni altra cache, eliminati dal più vecchio; lo scope predefinito `buildkit` viene sovrascritto da ogni build; l'API della cache di GitHub limita le richieste |
| `type=registry` | Un'immagine di cache separata nel tuo registry | Scarica la cache dal registry, carica quella nuova | Un login al registry con diritti di push; spazio e traffico del registry |
| `type=inline` | Dentro l'immagine stessa | Scarica l'immagine per leggerne la cache | Solo `mode=min`: i layer degli stage intermedi non vengono conservati |
| `type=local` + actions/cache | Una cartella salvata con actions/cache | Scarica e scompatta tutta la cartella, poi la carica | Cresce a ogni esecuzione se non usi [`reset=true`](https://docs.docker.com/build/cache/backends/local/) (Buildx 0.35.0 e successivi); conta nei 10 GB |

Qualunque backend scegli, [ordina il Dockerfile](https://docs.docker.com/build/cache/optimize/) in modo che i layer che cambiano meno vengano prima: copia il lockfile e installa le dipendenze prima di copiare i sorgenti. Altrimenti ogni commit invalida il layer di installazione, e nessuna cache lo riporta.

`mode=min`, il predefinito, conserva solo i layer dell'immagine finale. `mode=max` conserva i layer di ogni stage, quindi una build multi-stage fa più hit, e carica di più.

Una configurazione tipica con `type=gha`, con uno scope per ogni immagine:

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

**I cache mount non sopravvivono.** `RUN --mount=type=cache` (la cache di un package manager dentro la build) di default non viene conservato nella cache di GitHub Actions; la documentazione di Docker rimanda a [buildkit-cache-dance](https://github.com/reproducible-containers/buildkit-cache-dance) per spostarlo dentro e fuori da actions/cache, un download e un upload in più a ogni esecuzione.

## docker compose scarica tutte le immagini, a ogni job

I test di integrazione che avviano Postgres, Redis e qualche servizio con `docker compose up` scaricano ogni immagine a ogni job, perché la VM è nuova. Sui runner ospitati da GitHub le opzioni spostano solo il download:

- `docker save` delle immagini in un file tar, metterlo in cache con actions/cache e `docker load` nel job successivo. Conta nei 10 GB, e il caricamento richiede il suo tempo.
- Costruire le immagini dei servizi con buildx e uno dei backend di cache qui sopra, che lascia comunque da scaricare le immagini di base.

## Quando la soluzione è una macchina che conserva la cache di Docker

Ogni backend qui sopra esiste perché il builder dimentica. Un daemon Docker che resta tra un job e l'altro ha già i layer dell'ultima build, i suoi cache mount e ogni immagine che ha scaricato, sul suo disco. Non c'è niente da esportare, niente da importare, e nessun limite di 10 GB da condividere.

## Skipbox tiene la cache di Docker sulla tua macchina

Ogni piano include la macchina del tuo account, che resta tra un job e l'altro:

- **`docker build` e `docker compose build`** riusano i layer dell'ultima build, senza modifiche al workflow.
- **Le immagini restano sul disco.** `docker compose up` trova le immagini scaricate l'ultima volta; `docker compose pull` prende solo i layer cambiati.
- **I cache mount restano** con la cache di build di Docker, quindi `RUN --mount=type=cache` conserva la cache del package manager senza step in più.
- **docker/setup-buildx-action funziona così com'è.** Il suo builder parte dai layer che l'ultima build del tuo repository ha lasciato sulla macchina, e puoi togliere `cache-from` e `cache-to`. Nella nostra esecuzione della CI di un progetto pubblico su una macchina da 4 vCPU (19 novembre 2026, un'esecuzione per volta), lo step che costruisce l'immagine ha impiegato 177 s alla prima esecuzione e 4 s alla ripetizione, con 31 step CACHED.
- **Disco:** non si cancella niente finché, dopo un job, il disco non è quasi pieno. Allora se ne vanno prima le immagini orfane, poi la cache di build usata meno di recente.

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

Un job sceglie la sua dimensione con l'etichetta:

| Etichetta | Macchina | Disco | Piano |
|---|---|---|---|
| `skipbox` | 4 vCPU · 16 GB | 80 GB | S, $39 al mese |
| `skipbox-8x16` | 8 vCPU · 16 GB | 160 GB | M, $79 al mese |
| `skipbox-16x32` | 16 vCPU · 32 GB | 320 GB | L, $149 al mese |

I minuti sono illimitati. A 20.000 minuti al mese su 4 vCPU, GitHub fattura $222; Skipbox S costa $39, $183 in meno.

## Basta una riga

1. Accedi a Skipbox con GitHub.
2. Installa la GitHub App di Skipbox e scegli i repository.
3. Cambia `runs-on` e fai push.

Il primo job costruisce ogni layer. Il secondo li trova sulla macchina.

## Sicurezza

- La macchina è solo del tuo account. Nessun job di altre aziende gira su di essa.
- Dopo ogni job vengono cancellati le credenziali, i processi e i container del runner, e anche `~/.docker/config.json`, quindi un login al registry non passa al job successivo. “VM nuova per ogni job” dà invece a ogni job una macchina nuova.
- Il codice di chi non ha accesso in scrittura (come le pull request dai fork) gira su una macchina nuova, usata una volta e poi eliminata, mai sulla tua.

I dettagli sono in [come vengono isolati i job](https://docs.skipbox.dev/it/isolation).

## Provalo sulla tua build Docker

La prova è gratuita per 7 giorni o 3000 minuti di job, quello che arriva prima, e non chiede la carta. Sposta la tua build Docker su `runs-on: skipbox`, eseguila due volte e metti lo step di build della seconda esecuzione accanto a quello di GitHub.

## Domande frequenti

### Perché la cache dei layer Docker si perde a ogni esecuzione di GitHub Actions?

Perché ogni job su un runner ospitato da GitHub parte su una VM nuova, senza cache di build e senza le immagini dell'ultima esecuzione. docker/setup-buildx-action ci aggiunge del suo: di default crea un builder docker-container che parte vuoto e viene rimosso alla fine del job. Quindi ogni layer viene ricostruito, a meno che tu non esporti la cache con cache-to e la importi con cache-from, o non giri su una macchina che conserva la cache di build di Docker.

### Come si mettono in cache i layer Docker in GitHub Actions?

Sui runner ospitati da GitHub, con gli exporter di cache di buildx: cache-from: type=gha e cache-to: type=gha,mode=max in docker/build-push-action salvano i layer nella cache di Actions di GitHub (10 GB per repository, condivisi con ogni altra cache). type=registry li salva come immagine separata nel tuo registry, e type=local in una cartella che salvi con actions/cache. Con type=gha dai a ogni immagine il suo scope, perché lo scope predefinito viene sovrascritto da ogni build. Su una macchina che conserva il disco, docker build riusa i layer senza exporter.

### Perché buildx con cache-to type=gha è ancora lento?

Perché i layer viaggiano ancora. Con mode=max, ogni esecuzione carica ogni nuovo layer di ogni stage, e un'esecuzione successiva scarica i layer che le servono. La cache condivide con tutto il resto i 10 GB per repository di GitHub, quindi viene eliminata, e l'API della cache di GitHub limita una build che fa troppe richieste. Un builder che ha già i layer sul suo disco salta entrambe le direzioni.

### Come faccio a impedire che docker compose scarichi le stesse immagini a ogni job?

Su un runner ospitato da GitHub non puoi, puoi solo spostare il download: docker save delle immagini in un file tar, metterlo in cache con actions/cache e docker load nel job successivo. Conta negli stessi 10 GB ed è un download e un caricamento a ogni esecuzione. Su una macchina che conserva il disco, le immagini che compose ha scaricato l'ultima volta sono già lì, e docker compose pull prende solo i layer cambiati.

### Devo cambiare il workflow per conservare la cache di Docker su Skipbox?

Solo runs-on: la tua macchina conserva immagini, layer e cache di build di Docker tra un job e l'altro. docker build e docker compose build li riusano, e docker/setup-buildx-action funziona così com'è: il suo builder parte dai layer che l'ultima build del tuo repository ha lasciato sulla macchina. Puoi togliere cache-from e cache-to.

### Quanto costa provarlo?

Niente. La prova dura 7 giorni o 3000 minuti di job, quello che arriva prima, senza carta. Sposta la tua build Docker su runs-on: skipbox, eseguila due volte e confronta lo step di build della seconda esecuzione con quello di GitHub.

Aggiornata il giorno 2026-11-19 · https://skipbox.dev/it/guides/docker-layer-cache-github-actions
