# Cache de camadas Docker no GitHub Actions: por que todo build começa a frio, e como guardar as camadas

> Cada trabalho do GitHub Actions começa em uma VM nova, sem cache de build do Docker e sem imagens baixadas, e o builder padrão do setup-buildx-action começa vazio. O cache-to e o cache-from do buildx (gha, registry, local) trazem as camadas de volta como downloads, dentro dos 10 GB do GitHub. Um executor que guarda o cache de build do Docker no disco não precisa de nada disso, por $39 fixos por mês.

O cache de camadas do Docker se perde em cada execução do GitHub Actions porque cada trabalho em um executor hospedado pelo GitHub começa em uma VM nova: sem cache de build, sem imagens baixadas. O builder padrão do docker/setup-buildx-action (`docker-container`) também começa vazio em cada trabalho e é removido no fim dele. A solução de sempre é exportar o cache com o buildx. `cache-to: type=gha,mode=max` e `cache-from: type=gha` guardam as camadas no cache do Actions do GitHub, 10 GB por repositório e divididos com todos os outros caches; `type=registry` as guarda no seu registro; `type=local`, em um diretório que você salva com o actions/cache. Cada um troca um rebuild por um upload e um download a cada execução.

O Skipbox guarda as camadas onde o build roda. Os seus trabalhos rodam na máquina dedicada da sua conta, que guarda as imagens, as camadas e o cache de build do Docker entre os trabalhos, em um disco de 80 GB no S contra 14 GB no executor do GitHub. O `docker build` e o `docker compose build` reutilizam as camadas do último build, e as imagens que o compose baixou já estão no disco. O setup-buildx-action funciona como está, e o builder dele também encontra essas camadas. Troque uma linha, `runs-on: skipbox`, por $39 fixos por mês com minutos ilimitados.

- GitHub: uma VM nova por trabalho, então nenhuma camada, nenhuma imagem e um builder do buildx vazio a cada execução
- Skipbox: o cache de build e as imagens do Docker ficam no disco da sua máquina, então as camadas que não mudaram não são refeitas nem baixadas
- 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-docker-layer-cache-github-actions-pt-br)

## Por que todo build começa a frio

- **Uma VM nova por trabalho.** Segundo a [referência de executores](https://docs.github.com/en/actions/reference/runners/github-hosted-runners) do GitHub, cada executor hospedado pelo GitHub é uma máquina virtual (VM) nova hospedada pelo GitHub. Nada do que o último trabalho construiu ou baixou está nela.
- **Um builder vazio.** O [docker/setup-buildx-action](https://github.com/docker/setup-buildx-action) cria e inicia por padrão um builder com o driver `docker-container`, e o `cleanup` dele (ligado por padrão) remove o builder no fim do trabalho.
- **14 GB de disco.** O `ubuntu-latest` de um repositório privado tem 2 CPUs, 8 GB e 14 GB de SSD. Uma imagem grande, o cache de build dela e um arquivo de cache para descompactar podem esgotar o espaço ("no space left on device").

## Os backends de cache do buildx, e quanto cada um custa

Segundo a documentação do Docker sobre [backends de cache](https://docs.docker.com/build/cache/backends/) e [gerenciamento de cache com o GitHub Actions](https://docs.docker.com/build/ci/github-actions/cache/):

| Backend | Para onde vão as camadas | O que cada execução paga | Limites |
|---|---|---|---|
| `type=gha` | O cache do Actions do GitHub | Envia as camadas novas, baixa as que precisa | 10 GB por repositório com todos os outros caches, removidos dos mais antigos para os mais novos; o scope padrão `buildkit` é sobrescrito por cada build; a API de cache do GitHub limita a taxa |
| `type=registry` | Uma imagem de cache separada no seu registro | Baixa o cache do registro, envia o novo | Um login no registro com permissão de push; o armazenamento e o tráfego do registro |
| `type=inline` | Dentro da própria imagem | Baixa a imagem para ler o cache dela | Só `mode=min`: as camadas dos estágios intermediários não ficam |
| `type=local` + actions/cache | Um diretório salvo com o actions/cache | Baixa e descompacta o diretório inteiro, depois o envia | Cresce a cada execução, a menos que [`reset=true`](https://docs.docker.com/build/cache/backends/local/) (Buildx 0.35.0 em diante); conta nos 10 GB |

Qualquer que seja o backend, [ordene o Dockerfile](https://docs.docker.com/build/cache/optimize/) para que as camadas que menos mudam venham primeiro: copie o lockfile e instale as dependências antes de copiar o código. Senão, cada commit invalida a camada de instalação, e nenhum cache a traz de volta.

O `mode=min`, o padrão, guarda só as camadas da imagem final. O `mode=max` guarda as camadas de todos os estágios, então um build multiestágio acerta mais, e envia mais.

Uma configuração típica de `type=gha`, com um scope próprio por imagem:

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

**Os cache mounts não sobrevivem.** O `RUN --mount=type=cache` (o cache de um gerenciador de pacotes dentro do build) não fica no cache do GitHub Actions por padrão; a documentação do Docker aponta o [buildkit-cache-dance](https://github.com/reproducible-containers/buildkit-cache-dance) para levá-lo para dentro e para fora do actions/cache, mais um download e um upload a cada execução.

## O docker compose baixa todas as imagens, em todo trabalho

Os testes de integração que sobem Postgres, Redis e alguns serviços com `docker compose up` baixam todas as imagens em cada trabalho, porque a VM é nova. Nos executores hospedados pelo GitHub, as opções só mudam o download de lugar:

- `docker save` das imagens para um arquivo tar, cache dele com o actions/cache e `docker load` no próximo trabalho. Isso conta nos 10 GB, e o carregamento leva o próprio tempo.
- Criar as imagens dos serviços com o buildx e um dos backends de cache acima, o que ainda deixa as imagens base para baixar.

## Quando a solução é uma máquina que guarda o cache do Docker

Cada backend acima existe porque o builder esquece. Um daemon Docker que fica entre os trabalhos já tem as camadas do último build, os cache mounts dele e cada imagem que baixou, no próprio disco. Não há nada para exportar, nada para importar e nenhum limite de 10 GB para dividir.

## O Skipbox guarda o cache do Docker na sua máquina

Cada plano vem com a máquina dedicada da sua conta, mantida entre os trabalhos:

- **O `docker build` e o `docker compose build`** reutilizam as camadas do último build, sem mudança no workflow.
- **As imagens ficam no disco.** O `docker compose up` encontra as imagens que baixou da última vez; o `docker compose pull` busca só as camadas que mudaram.
- **Os cache mounts ficam** com o cache de build do Docker, então o `RUN --mount=type=cache` guarda o cache do gerenciador de pacotes sem nenhum step a mais.
- **O docker/setup-buildx-action funciona como está.** O builder dele começa nas camadas que o último build do seu repositório deixou na máquina, e você pode tirar o `cache-from` e o `cache-to`. Na nossa própria execução da CI de um projeto público em uma máquina de 4 vCPU (19 de novembro de 2026, uma execução de cada), o step que faz o build da imagem levou 177 s na primeira execução e 4 s na repetição, com 31 steps CACHED.
- **Disco:** nada é apagado até o disco estar quase cheio depois de um trabalho. Aí saem primeiro as imagens órfãs (dangling), depois o cache de build usado há mais tempo.

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

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 |

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

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.

O primeiro trabalho constrói todas as camadas. O segundo as encontra 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, e também o `~/.docker/config.json`, então um login no registro não passa para o próximo trabalho. 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 máquina nova, descartável, nunca na sua.

Os detalhes estão em [como os trabalhos são isolados](https://docs.skipbox.dev/pt-br/isolation).

## Teste no seu build Docker

O teste é grátis por 7 dias ou 3.000 minutos de trabalhos, o que vier primeiro, e não pede cartão. Mova o seu build Docker para `runs-on: skipbox`, rode-o duas vezes e coloque o step de build da segunda execução ao lado do do GitHub.

## Perguntas frequentes

### Por que o cache de camadas Docker se perde em cada execução do GitHub Actions?

Porque cada trabalho em um executor hospedado pelo GitHub começa em uma VM nova, sem cache de build e sem as imagens da última execução. O docker/setup-buildx-action piora isso: por padrão, ele cria um builder docker-container que começa vazio e é removido no fim do trabalho. Então cada camada é refeita, a menos que você exporte o cache com cache-to e o importe com cache-from, ou rode em uma máquina que guarda o cache de build do Docker.

### Como fazer cache das camadas Docker no GitHub Actions?

Nos executores hospedados pelo GitHub, com os exportadores de cache do buildx: cache-from: type=gha e cache-to: type=gha,mode=max no docker/build-push-action guardam as camadas no cache do Actions do GitHub (10 GB por repositório, divididos com todos os outros caches). O type=registry as guarda como uma imagem separada no seu registro, e o type=local em um diretório que você salva com o actions/cache. Dê a cada imagem o seu próprio scope com type=gha, já que o scope padrão é sobrescrito por cada build. Em uma máquina que guarda o disco, o docker build reutiliza as camadas sem exportador nenhum.

### Por que o buildx com cache-to type=gha continua lento?

Porque as camadas continuam viajando. Com mode=max, cada execução envia cada camada nova de cada estágio, e uma execução seguinte baixa as camadas de que precisa. O cache divide os 10 GB por repositório do GitHub com todo o resto, então ele é removido, e a API de cache do GitHub limita a taxa de um build que faz requisições demais. Um builder que já tem as camadas no disco pula as duas direções.

### Como impedir que o docker compose baixe as mesmas imagens em cada trabalho?

Em um executor hospedado pelo GitHub não dá, só mudar o download de lugar: docker save das imagens para um arquivo tar, cache dele com o actions/cache e docker load no próximo trabalho. Isso conta nos mesmos 10 GB e é um download e um carregamento a cada execução. Em uma máquina que guarda o disco, as imagens que o compose baixou da última vez já estão lá, e o docker compose pull só busca as camadas que mudaram.

### Preciso mudar o meu workflow para guardar o cache do Docker no Skipbox?

Só o runs-on: a máquina da sua conta guarda as imagens, as camadas e o cache de build do Docker entre os trabalhos. O docker build e o docker compose build reutilizam tudo isso, e o docker/setup-buildx-action funciona como está: o builder dele começa nas camadas que o último build do seu repositório deixou na máquina. Você pode tirar o cache-from e o cache-to.

### Quanto custa testar?

Nada. O teste dura 7 dias ou 3.000 minutos de trabalhos, o que vier primeiro, sem cartão. Mova o seu build Docker para runs-on: skipbox, rode-o duas vezes e compare o step de build da segunda execução com o do GitHub.

Atualizado em 2026-11-19 · https://skipbox.dev/pt-br/guides/docker-layer-cache-github-actions
