Skipbox

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

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.

Por que todo build começa a frio

  • Uma VM nova por trabalho. Segundo a referência de executores 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 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 e gerenciamento de cache com o GitHub Actions:

Qualquer que seja o backend, ordene o Dockerfile 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:

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

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.

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 19 de novembro de 2026

CI/CD mais rápido com um cache sempre aquecido

Seu executor aquecido a preço fixo

Nós hospedamos. Você muda uma linha. 1/12 do custo do GitHub com uso total. Preço fixo, então rode o dia todo. 7× o espaço de cache do GitHub.

  • Sem cartão
  • Entrar com o GitHub
  • Cancele quando quiser