# Limite de tamanho do cache do GitHub Actions: por que o seu cache é removido, demora para restaurar ou erra

> O cache do Actions do GitHub guarda 10 GB por repositório, apaga as entradas lidas há mais tempo quando você passa disso e descarta qualquer entrada sem uso há 7 dias. Mesmo um acerto é um download para uma VM nova. Quanto custa cada solução, e por que um executor que guarda o disco torna a maior parte do cache desnecessária, por $39 fixos por mês.

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.

- GitHub: 10 GB por repositório, entradas sem uso há 7 dias apagadas, cada acerto baixado de novo
- Skipbox: os caches de pacotes e as camadas do Docker ficam no disco da sua máquina, com pelo menos 7× o espaço de cache do GitHub
- 20.000 minutos por mês em 4 vCPU: $222 no GitHub, $39 no Skipbox

**GitHub Actions a preço fixo, minutos ilimitados** O Skipbox roda os seus trabalhos do GitHub Actions na sua própria máquina dedicada: $39 por mês, não importa quantos minutos você rode. As camadas Docker e o cache de dependências ficam entre os trabalhos, então o próximo trabalho começa na hora.

Um executor de 4 vCPU, 20.000 minutos por mês: GitHub $222 → Skipbox $39. Você economiza $183 todo mês.

A mudança é uma linha: `runs-on: skipbox`.

[Começar meu teste grátis de 7 dias](https://app.skipbox.dev/sign-in?ref=g-github-actions-cache-size-limit-pt-br)

## As regras de cache do GitHub

Segundo a [referência de cache de dependências](https://docs.github.com/en/actions/reference/workflows-and-actions/dependency-caching) do GitHub, a [cobrança do Actions](https://docs.github.com/en/billing/concepts/product-billing/github-actions) e o changelog dele sobre [caches acima de 10 GB](https://github.blog/changelog/2025-11-20-github-actions-cache-size-can-now-exceed-10-gb-per-repository/):

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

```bash
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](https://github.com/actions/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. As `restore-keys` dão uma correspondência parcial, e o `cache-hit` entã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 `~/.npm` ou do store do pnpm, não do `node_modules` nem da saída de build. Salve só no branch padrão, com `actions/cache/restore` em todo trabalho e `actions/cache/save` em um. Isso custa o seu tempo, e um cache menor restaura menos.
- **Corrigir as chaves.** Use o lockfile na chave, acrescente `restore-keys` e 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](https://skipbox.dev/pt-br/guides/rust-cache-slow-rust-ci):

- **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 `~/.cache` de cada ferramenta e os caches do Go, do Gradle, do Cargo e do Maven, com as ferramentas que os `setup-*` instalaram. Nada para restaurar.
- **As imagens, as camadas e o cache de build do Docker também ficam.** O `docker build` reutiliza as camadas do último build ([cache de camadas Docker](https://skipbox.dev/pt-br/guides/docker-layer-cache-github-actions)).
- **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

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

1. Entre no Skipbox com o GitHub.
2. Instale o app do Skipbox no GitHub e escolha os repositórios.
3. Troque o `runs-on` e 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](https://docs.skipbox.dev/pt-br/isolation).

## 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 2026-11-19 · https://skipbox.dev/pt-br/guides/github-actions-cache-size-limit
