Cache dei layer Docker in GitHub Actions: perché ogni build parte a freddo, e come conservare i layer
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.
Perché ogni build parte a freddo
- Una VM nuova per job. Il riferimento dei runner 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 crea e avvia di default un builder con il driver
docker-container, e il suocleanup(attivo di default) rimuove il builder alla fine del job. - 14 GB di disco. L'
ubuntu-latestdi 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 di Docker e dalla gestione della cache con GitHub Actions:
| 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 (Buildx 0.35.0 e successivi); conta nei 10 GB |
Qualunque backend scegli, ordina il Dockerfile 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:
- 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 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 savedelle immagini in un file tar, metterlo in cache con actions/cache edocker loadnel 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 buildedocker compose buildriusano i layer dell'ultima build, senza modifiche al workflow.- Le immagini restano sul disco.
docker compose uptrova le immagini scaricate l'ultima volta;docker compose pullprende solo i layer cambiati. - I cache mount restano con la cache di build di Docker, quindi
RUN --mount=type=cacheconserva 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-fromecache-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.
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
- Accedi a Skipbox con GitHub.
- Installa la GitHub App di Skipbox e scegli i repository.
- Cambia
runs-one 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.
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 19 novembre 2026