Limite di dimensione della cache di GitHub Actions: perché la cache viene eliminata, si ripristina lentamente o fa miss
GitHub Actions dà a ogni repository 10 GB di cache. Quando il repository li supera, GitHub salva comunque la nuova voce ed elimina le voci lette meno di recente finché non torna sotto il limite, ed elimina ogni voce che nessun job ha letto per 7 giorni. Un branch legge solo le sue cache e quelle del branch predefinito, quindi la prima esecuzione di un nuovo branch spesso fa miss. E un hit è comunque un download: ogni job su un runner ospitato da GitHub parte su una VM nuova, quindi scarica e scompatta di nuovo l'archivio. Puoi alzare il limite, a $0,07 per GB al mese oltre 10 GB, e regolare le chiavi, ma il download resta.
Skipbox toglie il download. I tuoi job girano sulla macchina del tuo account, che resta tra un job e l'altro, quindi le cache di npm, pnpm, Gradle, Go e Cargo e i layer Docker sono ancora sul suo disco dall'ultimo job (80 GB su S, contro i 14 GB del runner di GitHub). Quello che salva actions/cache resta accanto alla macchina, quindi un ripristino è una lettura locale. Cambi una riga, runs-on: skipbox, a un prezzo fisso di $39 al mese con minuti illimitati.
Le regole della cache di GitHub
Dal riferimento sulla cache delle dipendenze di GitHub, dalla fatturazione di Actions e dal suo changelog sulle cache oltre 10 GB:
| Regola | Cosa fa GitHub |
|---|---|
| Dimensione | 10 GB per repository di default, condivisi da tutti i branch e i workflow |
| Oltre la dimensione | Salva la nuova voce, poi elimina le voci per ultimo accesso, dalla più vecchia, finché il repository non torna sotto il limite. L'eliminazione gira ogni ora |
| Voci non usate | Elimina ogni voce non letta da più di 7 giorni |
| Un limite più alto | Su un account Pro, Team o Enterprise, gli admin possono alzare dimensione e giorni. Oltre 10 GB, $0,07 per GB al mese, sul picco di ogni ora. Un budget raggiunto rende la cache di sola lettura fino al ciclo di fatturazione successivo |
| Branch | Un'esecuzione ripristina le cache del suo branch e del branch predefinito; un'esecuzione di pull request anche quelle del branch di base. Mai quelle di un branch parallelo o figlio |
| Pull request | Le cache di una pull request sono legate al suo merge ref: le leggono solo le riesecuzioni di quella pull request |
| Voci | Non si possono modificare. Una chiave che esiste già non viene salvata di nuovo |
| Hit | cache-hit vale true solo per una corrispondenza esatta di key; una corrispondenza con restore-keys vale false |
| Frequenza | Fino a 200 upload e 1.500 download al minuto per repository |
Perché la cache viene eliminata
Gli stessi 10 GB contengono tutto quello che il repository salva. Ogni branch e ogni pull request salvano le loro voci. Una matrice di tre versioni di Node su due sistemi operativi ne salva sei. La cache di build type=gha di Docker finisce negli stessi 10 GB. Quando i salvataggi di un giorno superano il limite, ogni nuovo salvataggio elimina una voce più vecchia, spesso quella che serve al job successivo. GitHub lo chiama cache thrashing.
Per vedere cosa la riempie, elenca le voci per dimensione:
gh cache list --sort size_in_bytes --limit 20
La pagina Actions › Caches del repository mostra lo stesso, con il branch e l'ultimo uso di ogni voce.
Perché il ripristino è lento
Un hit della cache su un runner ospitato da GitHub è un download su una VM nuova, poi una decompressione. Il tempo cresce con l'archivio, quindi una cache cresciuta fino a diversi GB può durare quanto l'installazione che doveva saltare. Un download bloccato viene interrotto dal timeout di segmento di actions/cache, 10 minuti di default (SEGMENT_DOWNLOAD_TIMEOUT_MINS).
Quasi tutte le configurazioni ripristinano anche meno di quanto si pensa. L'input cache: di setup-node salva la cache di download del package manager, non node_modules: dopo il ripristino, npm ci installa comunque ogni pacchetto. La cache di pip di setup-python è uguale: i download tornano, l'ambiente si installa di nuovo.
Perché la cache fa miss
- La chiave è cambiata. Una chiave con
hashFiles('**/package-lock.json')fa miss a ogni modifica del lockfile.restore-keysdà una corrispondenza parziale, e alloracache-hitvalefalse. - Un nuovo branch. Può leggere le cache del branch predefinito, non quelle di un altro branch di feature. Se il branch predefinito non ha mai eseguito il workflow, non c'è niente da leggere.
- Eliminata. Se l'è presa il limite o i 7 giorni.
- Non è mai stata salvata. Le voci non si possono modificare, quindi una chiave che esiste non viene mai salvata di nuovo, e il contenuto in cache resta vecchio quanto il suo primo salvataggio. A una pull request da un fork può non essere permesso di salvare.
Passare file al job successivo della stessa esecuzione è un altro strumento. La cache è per l'esecuzione successiva; l'output di build che serve a un job successivo dello stesso workflow passa da actions/upload-artifact e actions/download-artifact. Gli artifact hanno il loro storage, separato dai 10 GB, e anche loro sono un download su una VM nuova.
Quanto costa ogni correzione sui runner di GitHub
- Alza il limite. Meno eliminazioni, a $0,07 per GB al mese oltre 10 GB (l'esempio di GitHub: 200 GB usati per intero costano $13,30 al mese), su un account Pro, Team o Enterprise. I ripristini restano download, e le cache più grandi si scaricano più lentamente.
- Salva meno. Metti in cache
~/.npmo lo store di pnpm, nonnode_modulesné l'output di build. Salva solo sul branch predefinito, conactions/cache/restorein ogni job eactions/cache/savein uno. Costa il tuo tempo, e una cache più piccola ripristina meno. - Correggi le chiavi. Basa la chiave sul lockfile, aggiungi
restore-keys, ed esegui il workflow sui push al branch predefinito, così i nuovi branch hanno qualcosa da leggere. - Un runner self-hosted che conserva il disco. Nessun download, nessun limite di 10 GB. La macchina la gestisci tu: aggiornamenti del sistema operativo, pulizia tra un job e l'altro senza cancellare le cache, e riparazioni quando si rompe.
Quando la soluzione è una macchina che conserva il disco
La cache esiste perché la macchina dimentica. Un runner ospitato da GitHub è una VM nuova per ogni job, quindi il job salva il suo stato nello storage di GitHub e lo riprende la volta dopo. Su una macchina che resta, quello stato è già sul suo disco: la cache del package manager, la tool cache, le immagini e la cache di build di Docker, perfino l'output di build.
La differenza si vede nella CI di progetti reali, dalle nostre esecuzioni dei loro job:
- astro (Node.js, Turborepo): 528 s su GitHub, 30 s su una macchina Skipbox, che conserva la cache di turbo, così le esecuzioni a caldo riproducono 40 task di build invece di eseguirli.
- helix (Rust): lo step di toolchain e cache ha richiesto 9-10 s sulla macchina Skipbox, contro 41-46 s su GitHub.
- tauri (Rust): 246 s su GitHub, 53 s sulla macchina Skipbox, con
target/conservato tra un job e l'altro.
Skipbox tiene la cache sulla tua macchina
Ogni piano include la macchina del tuo account, che resta tra un job e l'altro:
- Le cache dei pacchetti restano sul disco:
~/.npm, lo store di pnpm, la~/.cachedi ogni tool, e le cache di Go, Gradle, Cargo e Maven, con i tool chesetup-*ha installato. Niente da ripristinare. - Restano anche immagini, layer e cache di build di Docker.
docker buildriusa i layer dell'ultima build (cache dei layer Docker). - **actions/cache, setup-* e rust-cache non vanno cambiati.** Quello che salvano resta accanto alla macchina invece che nello storage di GitHub, con più spazio dei 10 GB per repository di GitHub, e un ripristino lo legge in locale.
- Nessuna scadenza a 7 giorni sul disco. Non si cancella niente finché, dopo un job, il disco non è quasi pieno; allora se ne va per primo quello usato meno di recente.
Almeno 7× lo spazio cache di GitHub su S. 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 |
L'ubuntu-latest di un repository privato ha 2 CPU, 8 GB e 14 GB di SSD. Su Skipbox 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
jobs:
test:
runs-on: skipbox # was ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
with:
node-version: 22
cache: npm
- run: npm ci && npm test
- Accedi a Skipbox con GitHub.
- Installa la GitHub App di Skipbox e scegli i repository.
- Cambia
runs-one fai push.
Lascia i tuoi step di cache come sono. La seconda esecuzione trova le cache della prima 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. “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 VM nuova che legge le tue cache ma non le può modificare.
I dettagli sono in come vengono isolati i job.
Provalo sul job la cui cache fa miss
La prova è gratuita per 7 giorni o 3000 minuti di job, quello che arriva prima, e non chiede la carta. Sposta quel job su runs-on: skipbox, eseguilo due volte e metti gli step di ripristino e di installazione della seconda esecuzione accanto a quelli di GitHub.
Domande frequenti
Qual è il limite di dimensione della cache di GitHub Actions?
10 GB per repository di default, per tutti i branch e i workflow insieme. Oltre, GitHub salva comunque la nuova voce ed elimina le voci in ordine di ultimo accesso, dalla più vecchia, finché il repository non torna sotto il limite. Le voci che nessun job ha letto per 7 giorni vengono eliminate a prescindere dalla dimensione. Su un account Pro, Team o Enterprise, gli admin possono alzare il limite e i giorni; lo spazio oltre 10 GB si paga $0,07 per GB al mese, misurato sul picco di ogni ora, e quando si raggiunge un budget la cache diventa di sola lettura fino al ciclo di fatturazione successivo.
Perché la mia cache di GitHub Actions viene eliminata così spesso?
Perché tutto il repository condivide gli stessi 10 GB: ogni branch, ogni pull request, ogni job della matrice e ogni sistema operativo salva le sue voci, e la cache type=gha di Docker finisce nello stesso posto. Quando i salvataggi di un giorno superano il limite, ogni salvataggio elimina una voce più vecchia, e il job successivo manca quella che gli serviva. GitHub lo chiama cache thrashing. Elenca le voci per dimensione (gh cache list --sort size_in_bytes) per vedere cosa la riempie.
Perché ripristinare la cache dura quanto installare da zero?
Perché un hit è comunque un download. Ogni job su un runner ospitato da GitHub parte su una VM nuova, quindi actions/cache scarica l'archivio e lo scompatta ogni volta, e più la cache è grande più ci vuole. La cache di setup-node riporta la cache di download del package manager, non node_modules, quindi npm ci installa comunque ogni pacchetto dopo il ripristino. Su un runner che conserva il disco, le cache sono già lì e non si scarica niente.
Perché actions/cache fa miss su un nuovo branch?
Un'esecuzione può ripristinare le cache del suo branch e del branch predefinito, e un'esecuzione di pull request anche quelle del suo branch di base. Non può leggere le cache di un branch parallelo. Quindi la prima esecuzione di un branch di feature fa hit solo se il branch predefinito ha salvato quella chiave. Esegui il workflow sui push al branch predefinito così salva, e aggiungi restore-keys per una corrispondenza parziale; cache-hit vale true solo per una corrispondenza esatta di key.
Quanta cache di Actions tiene Skipbox?
Più dei 10 GB per repository di GitHub, accanto alla tua macchina invece che nello storage di GitHub. Su una macchina cloud, quello che i job salvano con actions/cache, setup-* e rust-cache resta sul disco della macchina, fino a metà di quel disco (80 GB su S, 160 GB su M, 320 GB su L); su un host Skipbox, la cache dell'host tiene 20 GB per repository. In entrambi i casi una voce resta 7 giorni dopo l'ultimo uso, con le regole dei branch di GitHub. Le cache dei pacchetti e i layer Docker non passano di lì: restano sul disco stesso.
Cosa svuota le cache su una macchina Skipbox?
Niente tra un job e l'altro: le cache restano sulla macchina, e solo quando un job lascia il disco quasi pieno se ne va per primo quello usato meno di recente. La macchina riparte pulita con un ripristino: quando premi Ripristina macchina, quando la sua immagine viene aggiornata (almeno una volta al mese), quando non supera il controllo di salute dopo un job, e quando un job arriva al limite di 6 ore. Quando il piano finisce, la macchina viene eliminata con il suo disco.
Quanto costa provarlo?
Niente. La prova dura 7 giorni o 3000 minuti di job, quello che arriva prima, senza carta. Sposta il job la cui cache fa miss o si ripristina lentamente su runs-on: skipbox, eseguilo due volte e confronta gli step di ripristino e di installazione della seconda esecuzione con quelli di GitHub.
Aggiornata il giorno 16 novembre 2026