Manter verificações locais e de CI idênticas: um único ponto de entrada, ferramentas fixadas e o mesmo contêiner

Objetivo

Uma verificação que passa localmente passa no CI, e o inverso também vale. Assim desaparecem os commits do tipo "fix lint", as falhas que só ocorrem no CI e as discussões do tipo "na minha máquina funciona", e um agente pode confiar na sua execução local como previsão do resultado do pipeline.

Pré-requisitos

Um ponto de entrada em um task runner para cada verificação (veja o artigo relacionado), um manifesto de versões para a toolchain e um serviço de CI capaz de executar uma imagem de contêiner à sua escolha. A documentação do GitHub Actions descreve como executar os passos de um job dentro de um contêiner declarado com container: e image:; o asdf lê as versões das ferramentas de um arquivo .tool-versions e instala tudo o que está listado com asdf install; o mise lê o mesmo arquivo ou um mise.toml com uma seção [tools].

Passos

1. Defina cada verificação uma única vez como uma tarefa nomeada (lint, typecheck, test, build) e faça o workflow de CI chamar esses nomes e nada além deles. Quando o CI precisar de comportamento diferente (sem modo watch, saída legível por máquina), adicione uma flag aceita pela tarefa em vez de um segundo comando.
2. Fixe a toolchain em um manifesto versionado no repositório (.tool-versions, mise.toml ou o Dockerfile do dev container) e faça com que o bootstrap local e o job de CI instalem a partir dele; nunca use latest.
3. Execute o CI dentro da mesma imagem de contêiner que o ambiente de desenvolvimento usa, ou construa a imagem no CI a partir do mesmo Dockerfile, de modo que os pacotes do sistema operacional também coincidam.
4. Fixe as ferramentas que realizam as verificações (formatador, linter, test runner) no lock file do projeto, em vez de instalações globais, e invoque-as por meio da tarefa, de modo que a versão travada seja a única que possa ser executada.
5. Elimine diferenças de ambiente: evite caminhos de código que se comportem de forma diferente quando uma variável CI está definida, fixe locale e fuso horário dentro da tarefa (LC_ALL=C.UTF-8, TZ=UTC) e trate os caches como entradas opcionais, não como requisitos.
6. Adicione um job agendado que execute o conjunto completo de verificações a partir de um clone limpo, no contêiner e sem nenhum cache; ele detecta verificações que só passam localmente por causa de estado residual.
7. Quando o CI falhar e a execução local passar, trate a diferença como o bug: registre a discrepância (versão, variável de ambiente, arquivo ausente) e elimine-a antes de corrigir o sintoma.

Resultado esperado

O arquivo de workflow é curto: fazer checkout, instalar a partir do manifesto, executar as tarefas nomeadas. Qualquer pessoa que contribui reproduz uma falha do CI com o mesmo nome de comando, e o tempo do CI é gasto nas verificações, não em divergências de configuração.

Limites e base de verificação

O comportamento que depende de hardware (número de CPUs, limites de memória, GPU) continua a diferir e aparece em testes sensíveis a tempo. Segredos e credenciais de serviços diferem por concepção; verificações que precisam deles ficam fora do conjunto de paridade. Este é um procedimento proposto, baseado na documentação citada; não se afirma nenhum número de taxa de defeitos.

Execute as verificações em modo CI nos dois lados

Muitas ferramentas já mudam de comportamento quando a variável de ambiente CI está definida: test runners deixam de gravar novos snapshots e desativam o modo watch, gerenciadores de pacotes se recusam a modificar o lockfile e configurações de teste geradas por scaffolding proíbem testes focados. Esses ramos não podem ser removidos, então a regra de paridade é o inverso de evitá-los: a tarefa que executa o conjunto de verificações exporta CI=true por conta própria, de modo que a execução local e o pipeline sigam os mesmos ramos em todas as ferramentas de terceiros. O código do próprio projeto não deve ter nenhuma ramificação baseada em CI. Uma verificação que passa sem a variável e falha com ela passa então a ser reproduzível localmente com o mesmo comando.