Gate de Verificação e Automação
Visão Geral
Onde a verificação reside e o que a torna real. A CI é a fonte da verdade; o hook local é um espelho de conveniência. Uma regra não aplicada por um gate incontornável é uma sugestão (Princípio 7) — portanto, onde a plataforma não pode fornecer esse gate, o projeto declara modo advisory e carrega a regra deliberadamente, em vez de assumir mecanismos que não possui.
As Regras
- Um executor de tarefas é a entrada canônica para toda operação do dia a dia — test, build, dev, deploy são receitas nomeadas. Um procedimento que existe apenas na cabeça de alguém não acontece de forma confiável e não pode ser passado para um agente.
- A CI é a fonte da verdade — autoritativa, compartilhada e incontornável sempre que a plataforma permitir. Lint, typecheck, verificações de contrato, testes, varreduras de segurança, validação de commits — tudo é executado aqui e deve ser aprovado antes do merge no modo
enforced. O que a CI diz é o que conta. No modoadvisory, as mesmas verificações rodam e relatam; o gate é a disciplina, e isso nunca é motivo para executar menos verificações. - O hook de pre-push é um espelho de pré-submissão, não uma muralha. Ele executa as mesmas verificações rápidas localmente para que você provavelmente passe na CI antes de enviar. Ele é explicitamente contornável (
--no-verify) e só é executado onde o toolchain está instalado. Seu trabalho é velocidade e feedback rápido, não aplicação. O hook nunca bloqueia; a CI bloqueia sempre que a plataforma permitir. - Mantenha a CI rápida hierarquizando, não removendo verificações. Quando o conjunto completo excede a capacidade de todo PR, divida em presubmit (subconjunto rápido, bloqueia o PR) e postsubmit (conjunto completo, após o merge, bloqueia a promoção) — nunca mova verificações autoritativas de volta para o hook contornável.
- Imagens de contêiner são construídas na CI, identificadas pelo digest de conteúdo e publicadas com uma atestação de proveniência. Mantenha o custo acessível com cache de camadas do registry ou um runner auto-hospedado — nunca movendo a construção para um laptop, onde a proveniência do artefato não pode ser verificada por ninguém mais.
- Declare o modo de aplicação.
enforced— CI bloqueia merge via proteção de branch; o que a CI diz é o que conta.advisory— CI executa e relata, e o gate é a disciplina, porque a proteção de branch não está disponível (um repositório privado em um plano gratuito). Advisory é legítimo; alegar aplicação que você não tem não é. Indique o modo no primeiro registro de decisão do projeto e o que o moveria para enforced.
A Tensão Nomeada
Um presubmit local contornável é rápido mas inaplicável; a CI autoritativa é aplicável mas mais lenta. Resolva dando a cada um um mandato diferente — o hook otimiza o loop interno, a CI a correção do registro — e tornando a CI, não o hook, o que bloqueia um merge.
Racionalizações Comuns
| Desculpa | Realidade |
|---|---|
| "O hook de pre-push executa os testes, então a CI pode ser mínima" | O hook é contornável e depende de toolchain. Não pode ser a fonte da verdade. A CI deve reexecutar tudo. |
"Só vou usar --no-verify desta vez" | Tudo bem — porque a CI ainda pegará. É exatamente por isso que a CI, não o hook, é o gate. |
| "A CI está lenta, vamos mover os testes para o hook" | Hierarquize a CI (presubmit/postsubmit); nunca realoque verificações autoritativas para um gate contornável. |
| "As builds da CI são lentas, vou construir a imagem localmente" | Um artefato construído em laptop carrega proveniência que ninguém mais pode verificar. Corrija a latência com cache de camadas ou runner auto-hospedado. |
| "A proteção de branch custa dinheiro, então as regras não se aplicam" | As regras se aplicam; a aplicação difere. Declare modo advisory e mantenha a disciplina, ou torne o repositório público e obtenha proteção gratuita. |
Bandeiras Vermelhas — PARE
- Verificações autoritativas que existem apenas em um hook local
- CI que não reexecuta o que o hook executou
- Um merge permitido enquanto a CI está vermelha
- Uma imagem construída em qualquer lugar exceto na CI, ou promovida por tag em vez de por digest
- Um projeto se comportando como se a CI bloqueasse o merge quando não existe proteção de branch
Raciocínio completo: Artigo VIII da constituição, empacotado em engineering-constitution/references/engineering-constitution.md. Detalhes de deploy/k8s: cloud-delivery-aks.