Limite de tamanho do cache do GitHub Actions: por que o seu cache é removido, demora para restaurar ou erra
O GitHub Actions dá a cada repositório 10 GB de cache. Quando o repositório passa disso, o GitHub ainda salva a entrada nova e apaga as entradas lidas há mais tempo até voltar a ficar abaixo do limite, e apaga qualquer entrada que nenhum trabalho leu em 7 dias. Um branch só lê os próprios caches e os do branch padrão, então a primeira execução de um branch novo costuma errar. E um acerto ainda é um download: cada trabalho em um executor hospedado pelo GitHub começa em uma VM nova, então ele baixa e descompacta o arquivo de novo. Você pode aumentar o limite, a US$ 0,07 por GB por mês acima de 10 GB, e ajustar as suas chaves, mas o download continua.
O Skipbox elimina o download. Os seus trabalhos rodam na máquina dedicada da sua conta, que fica entre os trabalhos, então os caches do npm, do pnpm, do Gradle, do Go e do Cargo e as camadas do Docker continuam no disco dela desde o último trabalho (80 GB no S, contra 14 GB no executor do GitHub). O que o actions/cache salva fica ao lado da máquina, então uma restauração é uma leitura local. Troque uma linha, runs-on: skipbox, por $39 fixos por mês com minutos ilimitados.
As regras de cache do GitHub
Segundo a referência de cache de dependências do GitHub, a cobrança do Actions e o changelog dele sobre caches acima de 10 GB:
| Regra | O que o GitHub faz |
|---|---|
| Tamanho | 10 GB por repositório por padrão, divididos entre todos os branches e workflows |
| Acima do tamanho | Salva a entrada nova e depois apaga as entradas pelo último acesso, das mais antigas para as mais novas, até o repositório ficar abaixo do limite. A remoção roda a cada hora |
| Entradas sem uso | Apaga qualquer entrada não lida há mais de 7 dias |
| Um limite maior | Em uma conta Pro, Team ou Enterprise, os administradores podem aumentar o tamanho e os dias. Acima de 10 GB, US$ 0,07 por GB por mês, pelo pico de cada hora. Um orçamento atingido deixa o cache só de leitura até o próximo ciclo de cobrança |
| Branches | Uma execução restaura caches do próprio branch e do branch padrão; a execução de um pull request também do branch base dele. Nunca de um branch irmão ou filho |
| Pull requests | Os caches de um pull request ficam restritos ao merge ref dele: só as novas execuções daquele pull request os leem |
| Entradas | Não podem ser alteradas. Uma chave que já existe não é salva de novo |
| Acertos | cache-hit só é true quando a key corresponde exatamente; uma correspondência de restore-keys é false |
| Taxa | Até 200 uploads e 1.500 downloads por minuto por repositório |
Por que o cache é removido
Os mesmos 10 GB guardam tudo o que o repositório salva. Cada branch e cada pull request salvam as próprias entradas. Uma matriz de três versões do Node em dois sistemas operacionais salva seis. O cache de build type=gha do Docker cai nos mesmos 10 GB. Quando os salvamentos de um dia passam do limite, cada salvamento novo apaga uma entrada mais antiga, muitas vezes a de que o próximo trabalho precisa. O GitHub chama isso de cache thrashing.
Para ver o que o enche, liste as entradas por tamanho:
gh cache list --sort size_in_bytes --limit 20
A página Actions › Caches do repositório mostra o mesmo, com o branch e o último uso de cada entrada.
Por que a restauração é lenta
Um acerto de cache em um executor hospedado pelo GitHub é um download para uma VM nova, seguido de uma descompactação. O tempo cresce com o arquivo, então um cache que chegou a vários GB pode demorar tanto quanto a instalação que ele deveria pular. Um download travado é cortado pelo timeout de segmento do actions/cache, 10 minutos por padrão (SEGMENT_DOWNLOAD_TIMEOUT_MINS).
A maioria das configurações também restaura menos do que as pessoas pensam. O input cache: do setup-node salva o cache de downloads do gerenciador de pacotes, não o node_modules: depois da restauração, o npm ci ainda instala cada pacote. O cache do pip do setup-python é igual: os downloads voltam, o ambiente é instalado de novo.
Por que o cache erra
- A chave mudou. Uma chave com
hashFiles('**/package-lock.json')erra a cada mudança no lockfile. Asrestore-keysdão uma correspondência parcial, e ocache-hitentão lêfalse. - Um branch novo. Ele lê os caches do branch padrão, não os de outro branch de feature. Se o branch padrão nunca rodou o workflow, não há nada para ler.
- Removido. O limite ou os 7 dias o levaram.
- Nunca foi salvo. As entradas não podem ser alteradas, então uma chave que existe nunca é salva de novo, e o conteúdo em cache fica tão velho quanto o primeiro salvamento. Um pull request de um fork pode nem ter permissão para salvar.
Passar arquivos para o próximo trabalho da mesma execução é outra ferramenta. O cache é para a próxima execução; a saída de build de que um trabalho posterior do mesmo workflow precisa passa pelo actions/upload-artifact e pelo actions/download-artifact. Os artefatos têm armazenamento próprio, separado dos 10 GB, e também são um download para uma VM nova.
Quanto cada solução custa nos executores do GitHub
- Aumentar o limite. Menos remoções, a US$ 0,07 por GB por mês acima de 10 GB (o próprio exemplo do GitHub: 200 GB totalmente usados custam US$ 13,30 por mês), em uma conta Pro, Team ou Enterprise. As restaurações continuam sendo downloads, e caches maiores demoram mais para baixar.
- Salvar menos. Faça cache do
~/.npmou do store do pnpm, não donode_modulesnem da saída de build. Salve só no branch padrão, comactions/cache/restoreem todo trabalho eactions/cache/saveem um. Isso custa o seu tempo, e um cache menor restaura menos. - Corrigir as chaves. Use o lockfile na chave, acrescente
restore-keyse rode o workflow nos pushes para o branch padrão, para os branches novos terem o que ler. - Um executor auto-hospedado que guarda o disco. Sem download, sem limite de 10 GB. Você mantém a máquina: atualizações do sistema operacional, limpeza entre os trabalhos sem apagar os caches e conserto quando ela quebra.
Quando a solução é uma máquina que guarda o disco
O cache existe porque a máquina esquece. Um executor hospedado pelo GitHub é uma VM nova a cada trabalho, então o trabalho salva o próprio estado no armazenamento do GitHub e o busca de volta na próxima vez. Em uma máquina que fica, esse estado já está no disco: o cache do gerenciador de pacotes, o cache de ferramentas, as imagens e o cache de build do Docker, e até a saída de build.
A diferença aparece no CI de projetos reais, das nossas execuções dos próprios trabalhos deles:
- astro (Node.js, Turborepo): 528 s no GitHub, 30 s em uma máquina dedicada do Skipbox, que guarda o cache do turbo, então as execuções aquecidas dele reaproveitam 40 tarefas de build em vez de rodá-las.
- helix (Rust): o step de toolchain e cache levou 9-10 s na máquina dedicada, contra 41-46 s no GitHub.
- tauri (Rust): 246 s no GitHub, 53 s na máquina dedicada, com o
target/guardado entre os trabalhos.
O Skipbox guarda o cache na sua máquina
Cada plano vem com a máquina dedicada da sua conta, mantida entre os trabalhos:
- Os caches de pacotes ficam no disco:
~/.npm, o store do pnpm, o~/.cachede cada ferramenta e os caches do Go, do Gradle, do Cargo e do Maven, com as ferramentas que ossetup-*instalaram. Nada para restaurar. - As imagens, as camadas e o cache de build do Docker também ficam. O
docker buildreutiliza as camadas do último build (cache de camadas Docker). - **O actions/cache, os setup-* e o rust-cache não precisam de mudança.** O que eles salvam fica ao lado da máquina em vez de no armazenamento do GitHub, com mais espaço que os 10 GB por repositório do GitHub, e uma restauração o lê localmente.
- Nenhuma expiração de 7 dias no disco. Nada é apagado até o disco estar quase cheio depois de um trabalho; aí sai primeiro o que foi usado há mais tempo.
Pelo menos 7× o espaço de cache do GitHub no S. Um trabalho escolhe o tamanho pelo rótulo:
| Rótulo | Máquina | Disco | Plano |
|---|---|---|---|
skipbox | 4 vCPU · 16 GB | 80 GB | S, $39 por mês |
skipbox-8x16 | 8 vCPU · 16 GB | 160 GB | M, $79 por mês |
skipbox-16x32 | 16 vCPU · 32 GB | 320 GB | L, $149 por mês |
O ubuntu-latest de um repositório privado tem 2 CPUs, 8 GB e 14 GB de SSD. No Skipbox, os minutos são ilimitados. Com 20.000 minutos por mês em 4 vCPU, o GitHub cobra $222; o Skipbox S custa $39, $183 a menos.
Mudar é uma linha
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
- Entre no Skipbox com o GitHub.
- Instale o app do Skipbox no GitHub e escolha os repositórios.
- Troque o
runs-one faça push.
Deixe os seus steps de cache como estão. A segunda execução encontra os caches da primeira na máquina.
Segurança
- A máquina é só da sua conta. Nenhum trabalho de outra empresa roda nela.
- Depois de cada trabalho, as credenciais, os processos e os contêineres do executor são apagados. Limpar a cada trabalho dá, em vez disso, uma máquina nova a cada trabalho.
- O código de pessoas sem acesso de escrita (como pull requests de forks) roda em uma VM nova que lê os seus caches mas não pode alterá-los.
Os detalhes estão em como os trabalhos são isolados.
Teste no trabalho cujo cache erra
O teste é grátis por 7 dias ou 3.000 minutos de trabalhos, o que vier primeiro, e não pede cartão. Mova esse trabalho para runs-on: skipbox, rode-o duas vezes e coloque os steps de restauração e de instalação da segunda execução ao lado dos do GitHub.
Perguntas frequentes
Qual é o limite de tamanho do cache do GitHub Actions?
10 GB por repositório por padrão, para todos os branches e workflows juntos. Passando disso, o GitHub ainda salva a entrada nova e apaga as entradas pela ordem do último acesso, das mais antigas para as mais novas, até o repositório ficar abaixo do limite de novo. As entradas que nenhum trabalho leu em 7 dias são apagadas, qualquer que seja o tamanho. Em uma conta Pro, Team ou Enterprise, os administradores podem aumentar o limite e os dias; o armazenamento acima de 10 GB é cobrado a US$ 0,07 por GB por mês, medido pelo pico de cada hora, e quando um orçamento é atingido o cache passa a ser só de leitura até o próximo ciclo de cobrança.
Por que o meu cache do GitHub Actions é removido com tanta frequência?
Porque tudo no repositório divide os mesmos 10 GB: cada branch, cada pull request, cada trabalho de matriz e cada sistema operacional salva as próprias entradas, e o cache type=gha do Docker cai no mesmo lugar. Quando os salvamentos de um dia passam do limite, cada salvamento apaga uma entrada mais antiga, e o próximo trabalho não acha a de que precisava. O GitHub chama isso de cache thrashing. Liste as entradas por tamanho (gh cache list --sort size_in_bytes) para ver o que o enche.
Por que restaurar o cache demora tanto quanto instalar do zero?
Porque um acerto ainda é um download. Cada trabalho em um executor hospedado pelo GitHub começa em uma VM nova, então o actions/cache baixa o arquivo e o descompacta toda vez, e quanto maior o cache, mais isso demora. O cache do setup-node traz de volta o cache de downloads do gerenciador de pacotes, não o node_modules, então o npm ci ainda instala cada pacote depois da restauração. Em um executor que guarda o disco, os caches já estão lá e nada é baixado.
Por que o actions/cache erra em um branch novo?
Uma execução pode restaurar caches do próprio branch e do branch padrão, e a execução de um pull request também do branch base dele. Ela não lê os caches de um branch irmão. Então a primeira execução de um branch de feature só acerta se o branch padrão tiver salvado aquela chave. Rode o workflow nos pushes para o branch padrão para ele salvar, e acrescente restore-keys para uma correspondência parcial; o cache-hit só é true quando a key corresponde exatamente.
Quanto cache do Actions o Skipbox guarda?
Mais que os 10 GB por repositório do GitHub, ao lado da sua máquina em vez de no armazenamento do GitHub. Em uma máquina na nuvem, o que os trabalhos salvam com actions/cache, setup-* e rust-cache fica no próprio disco da máquina, até a metade desse disco (80 GB no S, 160 GB no M, 320 GB no L); em um host do Skipbox, o cache do host guarda 20 GB por repositório. Nos dois casos, uma entrada fica guardada 7 dias depois do último uso, com as regras de branch do GitHub. Os caches de pacotes e as camadas do Docker não passam por ele: ficam no próprio disco.
O que limpa os caches em uma máquina do Skipbox?
Nada entre os trabalhos: os caches ficam na máquina, e só quando um trabalho deixa o disco quase cheio sai primeiro o que foi usado há mais tempo. A máquina recomeça limpa numa redefinição: quando você clica em Redefinir máquina, quando a imagem dela é atualizada (pelo menos uma vez por mês), quando ela falha na verificação de integridade depois de um trabalho e quando um trabalho atinge o limite de 6 horas. A máquina é excluída com o disco quando o plano termina.
Quanto custa testar?
Nada. O teste dura 7 dias ou 3.000 minutos de trabalhos, o que vier primeiro, sem cartão. Mova o trabalho cujo cache erra ou demora para restaurar para runs-on: skipbox, rode-o duas vezes e compare os steps de restauração e de instalação da segunda execução com os do GitHub.
Atualizado em 19 de novembro de 2026