# Cache de camadas Docker

> O Latchkey Docker Cache Build envolve o docker buildx com cache de camadas apoiado em registry, então builds repetidos de imagens reaproveitam cada camada inalterada entre runners efêmeros.

Source: https://latchkey.dev/pt/documentation/docker-layer-caching

## Summary

- Um passo: `latchkey-dev/docker-cache-action@v1` envolve o `docker buildx build` com cache de camadas apoiado em registry.
- As camadas persistem entre os runners de uso único da Latchkey; apenas as camadas que suas mudanças invalidam são reconstruídas.
- Configuração zero: o registry de cache, as credenciais e as permissões já vêm provisionados por organização.
- Portável: em runners que não são Latchkey, o mesmo passo detecta que não há registry e faz o build normalmente, sem flags de cache.

Cada runner Latchkey é uma instância nova e isolada. Isso é bom para segurança e ruim para o cache local de camadas do Docker, que desaparece junto com o runner. O **Latchkey Docker Cache Build** resolve isso com um cache de camadas armazenado em um registry de containers privado gerenciado pela Latchkey para sua organização: camadas correspondentes de builds anteriores são reaproveitadas, e o cache atualizado é gravado de volta para o próximo run.

## Adicione ao seu workflow

```.github/workflows/build.yml
jobs:
  build:
    runs-on: latchkey-medium
    steps:
      - uses: actions/checkout@v4
      - uses: latchkey-dev/docker-cache-action@v1
        with:
          context: .
          tags: myapp:latest
          push: true
```

Essa é a integração inteira: você fornece as entradas que daria a qualquer build Docker, e a Latchkey cuida do registry, das credenciais e da conexão do cache. Por padrão a action usa `cache-mode: max`, que faz cache de todas as camadas, incluindo camadas intermediárias de builds multi-stage. Builds de plataforma única com `push: false` carregam a imagem construída no daemon Docker local do runner.

## Quanto vale o cache de camadas: um exemplo prático

Números ilustrativos, não um benchmark medido. Considere uma imagem Node.js multi-stage que leva ~8 minutos para construir sem cache: imagem base, pacotes de sistema, instalação de dependências, compilação, montagem. Com o cache de camadas no lugar, uma mudança só de código-fonte invalida apenas as camadas finais; tudo acima delas é puxado do cache do registry, e o rebuild fica na **faixa de 1 a 2 minutos**. Um commit que toca o stage de dependências invalida mais camadas e reconstrói mais, então o ganho escala com o quanto do seu Dockerfile uma mudança típica deixa intocado. O `cache-mode: max` padrão troca um push de cache maior após o build por melhores taxas de acerto exatamente nesses rebuilds multi-stage, já que camadas de stages intermediários também entram no cache.

## Entradas e saídas

| Entrada | Padrão | O que faz |
| --- | --- | --- |
| `tags` | obrigatório | Tags para a imagem construída |
| `context` | `.` | Caminho do contexto de build |
| `dockerfile` | `Dockerfile` | Caminho para o Dockerfile |
| `push` | `false` | Faz push da imagem construída |
| `build-args` | nenhum | Argumentos de build; os valores são mascarados nos logs pois podem conter segredos |
| `target` | nenhum | Stage alvo para builds multi-stage |
| `platforms` | nenhum | Plataformas alvo para o build |
| `cache-mode` | `max` | Escopo do cache: `min` ou `max` (max faz cache de todas as camadas, incluindo camadas intermediárias de multi-stage) |
| `cache-tag` | `cache` | Tag do registry usada para o cache de camadas |
| `extra-cache-from` / `extra-cache-to` | nenhum | Fontes e destinos de cache adicionais passados para o build |

| Saída | O que ela indica |
| --- | --- |
| `cache-configured` | `true` quando o cache de camadas via registry esteve ativo para o build, `false` caso contrário |
| `image-digest` | Digest da imagem construída |

## Seguro em qualquer runner

- **Em runners que não são Latchkey** (por exemplo, hospedados no GitHub), a action detecta que o registry de cache não está disponível e faz o build normalmente, sem flags de cache. Um único arquivo de workflow permanece portável entre tipos de runner.
- **No primeiro build de um repositório** o cache está vazio; se um build com cache falhar nesse primeiro run, a action automaticamente refaz sem cache. Os primeiros runs nunca quebram por causa do cache.
- **Os valores de build-arg são mascarados** nos logs, então segredos passados como build args não vazam para a saída do job.
- Caches são **isolados por organização**.

> ****
> Combine isso com um [runner de AI Scan customizado](/documentation/custom-runners) que pré-baixa suas imagens base, e os builds de imagem pulam tanto o download quanto as camadas inalteradas.

### Como o cache de camadas Docker funciona em runners efêmeros?

O `latchkey-dev/docker-cache-action@v1` envolve o `docker buildx build` com um cache de camadas apoiado em registry, então as camadas persistem no registry e não na máquina. Cada runner de uso único baixa as camadas que sua mudança não invalidou e reconstrói apenas as que invalidou.

### Preciso configurar um registry ou credenciais?

Não. O registry de cache, suas credenciais e as permissões são provisionados por organização, então o passo funciona sem configuração. Não há nada para criar nem secret para adicionar.

### A action funciona em runners que não são Latchkey?

Sim. Em um runner sem registry de cache do Latchkey disponível, o passo detecta isso e executa um `docker buildx build` normal, sem flags de cache, então um workflow compartilhado entre tipos de runner não precisa de ramificações.

---

Latchkey runs CI/CD that repairs its own failures. Agent entry points: https://latchkey.dev/agent.txt, https://latchkey.dev/openapi.json, https://latchkey.dev/llms.txt