Quais gates de pull request de agentes devem bloquear o merge?

Um agente pode produzir um diff limpo, uma descrição convincente e código que passa por uma revisão rápida, mas ainda deixar o aplicativo exposto ou impossível de recuperar. A decisão de merge deve depender de evidências que o repositório consegue medir, não da confiança do agente ou do tamanho reduzido do patch.

Eu uso sete gates bloqueadores: testes, CodeQL, revisão de dependências, detecção de segredos, verificações de autorização, ensaio de migração e verificação de rollback. Cada um responde a um tipo diferente de falha. Uma suíte verde não prova que um pacote novo é seguro, e uma análise estática limpa não informa se a migração vai bloquear a tabela mais movimentada.

Esses gates valem igualmente para mudanças de humanos e agentes. O agente muda o volume, a velocidade e a forma dos erros, mas não justifica uma via separada e mais fraca. Se uma mudança não consegue fornecer as mesmas evidências de qualquer outro pull request, ela não está pronta para o merge.

Um gate deve produzir evidências, não conselhos

Um gate de merge deve devolver um resultado reproduzível de aprovação ou falha para o commit exato que entrará no branch protegido. Um comentário dizendo para revisar uma dependência é um conselho. Um check obrigatório que identifica pacote, versão, advisory e limite de severidade é uma evidência.

A diferença importa porque muitos recursos de segurança apenas informam depois do momento útil para decidir. Um scanner pode criar um alerta, enviar e-mail ou abrir uma issue enquanto o botão de merge continua disponível. A equipe diz que o scanning está ativo, embora não consiga impedir a mudança. Confira quatro propriedades em cada gate:

• Ele roda no head commit atual do pull request.
• A proteção de branch exige o resultado com aquele nome.
• Um job ignorado, expirado ou interrompido não conta como aprovado.
• O resultado registra detalhes suficientes para reproduzir a decisão.

Mantenha a política no repositório. Um manifesto pequeno é mais fácil de revisar do que uma coleção de configurações conhecidas apenas pelos administradores:

merge_gates:
  tests: required
  codeql: required
  dependency_review: required
  secret_scan: required
  authorization: required
  migration_rehearsal: required_when_changed
  rollback_verification: required

required_when_changed não é uma brecha. O gate primeiro detecta os arquivos relevantes e depois executa o ensaio ou registra claramente not applicable. Não deixe filtros de caminho manterem um check obrigatório pendente para sempre, nem permita que o agente isente a própria mudança arriscada.

Restrinja as permissões do workflow ao mínimo necessário para cada job. Código de pull request é uma entrada não confiável, mesmo quando o branch pertence à sua organização. Um gate que expõe um token de escrita ou segredo de produção ao código examinado pode criar um problema pior do que aquele que deveria detectar.

Proteja a identidade do check como protege a lógica. Regras de branch normalmente exigem um nome de status, então dois workflows que publicam o mesmo nome podem permitir que o job mais fraco satisfaça a regra. Dê um nome único ao job de política, restrinja quem altera seu arquivo e exija revisão dos proprietários. Se uma fila de merge criar um novo commit combinado, rode os gates novamente nele ou vincule os resultados à revisão enfileirada. A evidência do head de ontem não vale para o merge de hoje.

Trate a configuração do gate como código sensível. Um pull request que altera um limite, remove um caminho, reduz um pacote de consultas ou adiciona uma exceção muda o sentido de todos os resultados verdes posteriores. Mostre os diffs de política com clareza e peça revisão de um mantenedor que entenda o controle afetado. O agente pode propor a alteração, mas não deve passar com mais facilidade por editar o mecanismo que o julga.

Testes bloqueiam regressões observáveis

O gate de testes deve bloquear toda mudança que quebre o comportamento especificado nas versões suportadas do runtime e do banco. Ele deve usar as mesmas entradas de build do commit de merge, incluindo dependências travadas, arquivos gerados, feature flags e estado do schema.

Agentes são bons em satisfazer a assertion mais próxima. Eles podem adicionar um fallback que deixa um teste verde e quebra tratamento de erros, paginação, concorrência ou um contrato de API vizinho. Exija testes novos ou modificados quando o comportamento mudar, mas não meça qualidade por linhas de teste. Verifique se o teste falharia se a implementação fosse removida ou revertida.

Um gate útil tem camadas com nomes separados:

• Testes unitários para lógica local e casos-limite.
• Testes de integração para contratos de banco, fila, cache e serviços externos.
• Testes de contrato para formatos públicos de request e response.
• Um smoke test pequeno do artefato construído.

Corrija testes instáveis em vez de repeti-los automaticamente até ficarem verdes. Uma tentativa extra pode coletar dados de diagnóstico, mas o status final deve mostrar a primeira falha. Caso contrário, o agente pode fazer merge de código cuja única propriedade comprovada é funcionar às vezes.

O smoke test deve iniciar o artefato, exercitar um endpoint de saúde e um caminho de escrita relevante, e encerrá-lo corretamente. Testar o source sem iniciar o aplicativo empacotado deixa passar arquivos ausentes, defaults ruins de ambiente, migrações quebradas e falhas no startup. O resultado de um serviço web pode ter formato compacto:

{"commit":"abc123","build":"pass","startup_ms":842,"health":200,"write_read_cycle":"pass"}

Não use um percentual universal de cobertura como gate principal. A cobertura pode mostrar uma mudança sem teste, mas um repositório alcança números altos com assertions fracas. Bloqueie pelas suítes obrigatórias e pelo comportamento modificado, e use o movimento da cobertura como evidência de revisão.

Proteja os testes da implementação que eles julgam. Se um pull request muda uma regra e reescreve as assertions para aceitar o novo resultado, a suíte pode passar enquanto o contrato se desloca em silêncio. Um reviewer deve comparar os testes alterados com a API pública, a issue ou a regra de aceitação. Para parsers, validadores, cobrança e acesso, adicione mutation testing ou entradas propositalmente erradas. A pergunta útil é se a suíte rejeita uma implementação incorreta plausível.

Guarde artefatos quando o gate falhar. Salve a seed que causou falha no teste aleatório, a imagem exata do banco, logs de serviço sem segredos e o comando de reprodução. Um status sem esses dados devolve o próximo agente ou engenheiro às suposições. Limite a retenção conforme as regras de dados e nunca envie um snapshot de produção só para facilitar a reprodução.

CodeQL bloqueia caminhos conhecidos para vulnerabilidades

O gate do CodeQL deve bloquear novos achados de alta confiança nas linguagens e artefatos gerados que o CodeQL realmente analisa. Um resultado limpo não deve sugerir que todo o aplicativo está seguro.

O GitHub descreve o CodeQL como um sistema que compila código em um banco consultável e executa queries sobre ele. O modelo acompanha os dados pelo código em vez de buscar apenas texto suspeito. Ele também é limitado pelo suporte a linguagens, sucesso do build, seleção de queries e código presente na análise. Se o build do banco excluir um serviço silenciosamente, o resultado verde cobre menos do que os reviewers imaginam.

Use um workflow com linguagens explícitas e política fixa de queries:

name: codeql
on: [pull_request]
permissions:
  contents: read
  security-events: write
jobs:
  analyze:
    strategy:
      matrix:
        language: [javascript-typescript, go]
    steps:
      - uses: actions/checkout@v4
      - uses: github/codeql-action/init@v3
        with:
          languages: ${{ matrix.language }}
          queries: security-extended
      - uses: github/codeql-action/autobuild@v3
      - uses: github/codeql-action/analyze@v3

Em um repositório real, fixe actions de terceiros em digests de commits revisados. Tags deixam o exemplo legível, mas uma tag mutável amplia a fronteira de confiança de um job de segurança obrigatório.

Decida o que bloqueia antes do primeiro alerta. Normalmente bloqueio achados novos no limite acordado de severidade e precisão, enquanto a dívida existente permanece visível em uma baseline. Bloquear todo o histórico no primeiro dia incentiva descartes em massa. Ignorá-lo para sempre cria um ponto cego. Dê responsáveis e prazos à baseline.

Inspecione o conjunto de arquivos analisados quando serviços, linguagens ou comandos de build mudarem. Um novo client mobile, resolver gerado ou backend separado pode exigir outro analisador ou etapa de build. “CodeQL passou” só é significativo quando os reviewers conseguem dizer o que ele examinou.

Separe falhas de análise de análises limpas. Se o autobuild não compilar um pacote, o job deve informar falha de infraestrutura ou configuração, não zero achados. Salve o log de criação do banco e a contagem de fontes analisadas por linguagem. Compare com o branch base e marque quedas grandes sem explicação. Isso detecta uma falha comum: uma alteração no build exclui o módulo vulnerável e o check fica rápido e verde porque viu menos código.

Revise descartes como mudanças de política, não como limpeza. Um falso positivo precisa de explicação concreta ligada ao caminho e à query. Comentários de supressão devem ser restritos, ter dono e aparecer no diff. Uma exclusão global de arquivos gerados pode ser adequada, mas primeiro confirme que não há templates ou entradas do gerador mantidas manualmente naquele diretório.

A revisão de dependências para o risco antes da instalação

A revisão deve bloquear quando o diff introduz um pacote ou versão que viola uma política explícita. Ela pode abranger severidade de advisories conhecidos, licenças negadas, fontes inesperadas e dependências diretas sem responsável.

Esse gate não é igual a um alerta de vulnerabilidade do repositório. O alerta diz que há uma dependência vulnerável no branch. A revisão pergunta se este pull request piora o grafo. A ferramenta do GitHub compara manifestos e lockfiles, então a decisão chega a tempo e fica atribuída à mudança.

Exija consistência do lockfile. Se um agente alterar package.json sem o lockfile, ou editar o lockfile sem uma mudança correspondente no manifesto, o job deve falhar. Comandos que resolvem versões novas em CI geram resultados não determinísticos e podem testar outro grafo.

Uma política compacta pode ser:

dependency_policy:
  fail_on_severity: high
  deny_licenses:
    - AGPL-3.0
  allow_sources:
    - registry.npmjs.org
    - proxy.golang.org
  require_owner_for_direct_additions: true

A lista exata de licenças é uma decisão jurídica e de produto, não um valor para copiar sem pensar. O útil é o repositório declará-la e o check imprimir o pacote que a acionou.

Não aprove automaticamente um pacote porque o nome parece com uma biblioteca sugerida. Agentes podem inventar nomes, escolher forks abandonados ou adicionar um client enorme para um helper pequeno. A saída deve mostrar pacotes diretos e transitivos novos, registry, versão resolvida, licença e status dos advisories. O reviewer pode então decidir se o código existente ou uma dependência menor já resolve.

Falhe de forma fechada se o serviço não produzir um diff. Um feed de advisories indisponível pode justificar segurar o merge, não transformar incerteza em verde. Um procedimento de emergência pode permitir override documentado por um mantenedor identificado, com o motivo anexado ao commit.

Verifique o comportamento da instalação em um job isolado cujo acesso de rede esteja limitado a registries aprovados. Lifecycle scripts e plugins de build executam código durante a instalação, portanto um pacote pode ser perigoso mesmo sem import. Registre scripts novos, binários nativos e registries desconhecidos. Não dê ao job credenciais de publicação, tokens de nuvem nem um cache gravável compartilhado com builds confiáveis.

Código vendorizado e imagens de container entram na mesma decisão, mesmo que a revisão normal não os veja. Compare digests, nomes de imagens base, submódulos Git e arquivos incluídos. Exija digests imutáveis para entradas de release. Uma tag como latest impede a reprodução posterior porque os bytes podem mudar sem outro diff.

A detecção de segredos deve inspecionar o diff e o histórico

O scanning deve bloquear quando o pull request introduzir um padrão de credencial ou um segredo ativo verificado, mesmo em fixture de teste, arquivo apagado, bundle gerado ou commit anterior.

Push protection e scanning de pull request resolvem problemas relacionados, mas diferentes. A primeira pode parar um segredo antes do remote. O gate examina o que já chegou e cobre colaboradores ou tipos de token que foram ignorados. Um alerta sem proteção de branch não bloqueia merge.

Escaneie o intervalo completo de commits em relação ao branch base, não apenas o filesystem final. O agente pode adicionar um token em um commit e removê-lo no seguinte; ele continua no histórico Git e talvez já esteja em logs ou caches. Trate-o como exposto. Revogue ou rotacione a credencial, limpe o histórico proposto e rode o check novamente.

Use fixtures sintéticos que não consigam autenticar. Eles devem se identificar como teste e corresponder a um padrão local, em vez de copiar a forma de uma chave real. Allowlists amplas são perigosas porque acidentes e atacantes acabam encontrando o diretório ignorado. Mantenha exceções exatas, revisadas e próximas da configuração.

Combine detectores de padrão com entropia e, quando o provedor oferecer com segurança, verificação de credencial. O padrão tem menos riscos de rede e exposição, mas perde tokens próprios. A verificação reduz a dúvida, porém envia parte do segredo candidato a outro serviço e nunca deve usar um endpoint não confiável fornecido pelo pull request. Documente o que verifica, o que fica local e quais dados saem de CI.

Escaneie codificações comuns e saídas geradas sem tratar toda string aleatória como credencial. Base64, URL encoding e bundles minificados podem esconder um segredo que apareceu em claro numa etapa anterior. Defina o limite com fixtures testados e revise atualizações do detector como política. Um scanner ruidoso ensina os mantenedores a descartar; um scanner silencioso cria confiança falsa.

A saída precisa mostrar o local sem revelar o valor:

{"result":"fail","detector":"generic-api-token","commit":"abc123","path":"config/dev.env","line":7,"fingerprint":"sha256:8f2c..."}

Nunca imprima a correspondência completa em logs de CI ou comentários. O mascaramento pode chegar tarde porque sistemas de log, notificações e artefatos já copiaram a saída.

Secret scanning não substitui a revisão das permissões do repositório. Um workflow pode ler um segredo de produção sem colocá-lo no diff, e um agente pode alterar um job de deploy para extraí-lo. Afaste segredos dos jobs de pull request, restrinja permissões e exija revisão humana nas definições de CI.

As verificações de autorização mantêm ações proibidas

O gate de autorização deve provar que cada operação protegida rejeita o ator errado e permite o ator previsto na fronteira do serviço. Testes de login sozinhos não testam autorização.

Equipes confundem autenticação, autorização e visibilidade da interface. Autenticação estabelece quem enviou o request. Autorização decide se a identidade pode executar a ação naquele objeto. Esconder um botão de admin em React não muda a decisão de uma API Go. Se o backend aceita o request, o aplicativo continua exposto.

Crie uma matriz de permissões para endpoints e ações alterados, incluindo propriedade e limites entre tenants:

read_private_project:
  anonymous: deny
  member: deny
  other_tenant: deny
  owner: allow
  admin: allow
update_project:
  anonymous: deny
  other_tenant: deny
  owner: allow

Gere testes da matriz ou escreva casos tabulares na linguagem do serviço. Cada caso negado deve chamar o handler real com identificadores realistas. Um mock que substitui o middleware pode provar que a rota funciona e ignorar justamente o controle testado.

Teste acesso no nível do objeto, não apenas roles. Dois usuários podem ter role member e pertencer a organizações diferentes. Mude separadamente identificadores de recurso e tenant para detectar referências diretas inseguras. Teste também endpoints em lote, exportações, jobs em segundo plano e resolvers GraphQL, que muitas vezes evitam checks dos handlers REST comuns.

Faça o gate falhar quando uma rota protegida nova não tiver regra. A autorização ausente deixa de ser intuição e vira defeito mensurável. O servidor deve negar por padrão. Uma regra allow explícita é mais fácil de auditar do que código espalhado que nega alguns casos conhecidos.

Agentes costumam reutilizar um handler vizinho, manter o caminho feliz e perder a verificação de propriedade. A matriz torna a omissão visível e oferece contrato estável quando roles ou regras de tenant mudarem.

Exercite autorização depois de normalizar as entradas. Maiúsculas, formatos alternativos de identificador, parâmetros duplicados e referências aninhadas podem enviar requests equivalentes por caminhos diferentes. Teste o endpoint direto e rotas batch ou de importação que chegam à mesma ação. Se um worker fizer a gravação final, propague ator e tenant ao job, em vez de tratá-lo como usuário confiável com poder total.

Registre a decisão esperada e a regra que a produziu sem expor dados privados. Uma falha útil informa classe de ator, ação, classe de objeto e status esperado. Ela não despeja token nem registro completo. Assim o reviewer distingue um fixture quebrado de uma mudança real de privilégio.

O ensaio de migração mede bloqueios e reversibilidade

O gate de migração deve aplicar cada alteração de schema a uma cópia com formato de produção, executar testes de compatibilidade e registrar duração, locks e rollback antes do merge. Uma migração que funciona em banco vazio prova muito pouco.

Use snapshot sanitizado ou dados gerados com tamanhos, índices, constraints e distribuição semelhantes. Dados exatos de produção não pertencem à infraestrutura de pull request. O objetivo é recriar pressão operacional sem copiar registros pessoais ou confidenciais.

Ensaie a sequência real de deployment. Se instâncias antigas continuarem ativas durante a migração, teste código antigo no schema novo e código novo no schema de transição. Adicionar coluna nullable costuma ser compatível. Renomeá-la em uma etapa pode quebrar todas as instâncias antigas que atendem tráfego.

Registre evidência legível por máquina:

{"migration":"20260727_add_project_state","apply_ms":18420,"max_lock_ms":310,"old_app_probe":"pass","new_app_probe":"pass","down":"pass"}

Defina limites por banco e classe de tabela. Um lock de 300 milissegundos pode ser inofensivo em uma tabela e problemático em outra. O reviewer deve ver o limite escolhido, o resultado medido e a versão do banco usada.

No PostgreSQL, inspecione operações que reescrevem tabela, validam constraint ou constroem índice bloqueando gravações. Prefira expandir e contrair: adicione a forma nova, faça deploy de código compatível com ambas, preencha em lotes controlados, mude leituras e remova a forma antiga depois. Outro pull request custa menos do que improvisar durante uma indisponibilidade.

Nem toda migração pode ter uma operação down segura. Apagar coluna perde dados e reverter uma transformação pode ser ambíguo. Nesses casos, exija recuperação para a frente ou ponto de restore testado. Chamar uma migração irreversível de segura só porque há arquivo down não é honesto.

Teste novas tentativas e falhas parciais. Um deploy pode parar depois de criar um índice e antes de registrar a migração, e a próxima tentativa não pode corromper estado nem falhar sempre. Interrompa o ensaio num limite controlado, repita e compare schema e ledger. Um backfill longo deve continuar de um cursor registrado, e rodar um lote duas vezes não pode duplicar nem apagar dados.

Meça disco e replicação além do tempo. Reescrever tabela pode consumir espaço temporário, ampliar write ahead logs e atrasar réplicas depois que a operação principal terminou. O gate não precisa prever produção com perfeição, mas deve registrar valores no conjunto de ensaio e compará-los com limites do responsável. Sem isso, uma migração local rápida pode esgotar o volume de produção.

A verificação de rollback deve executar a recuperação

O gate deve fazer deploy do candidato num ambiente isolado, criar estado representativo, executar o método de rollback suportado e provar que a versão anterior ainda lê e escreve corretamente. Um plano escrito não é verificação.

Separe rollback do aplicativo e dos dados. Devolver tráfego ao binário anterior pode levar segundos, enquanto desfazer um schema destrutivo pode ser impossível. O gate deve informar ambos. Se o aplicativo antigo não roda no schema novo, marque o candidato como não reversível e exija deploy em etapas.

Uma sequência prática:

1. Fazer deploy do commit main atual e criar registros representativos.
2. Atualizar para o artefato do pull request e exercitar caminhos alterados.
3. Criar novos registros no estado atualizado.
4. Restaurar o artefato anterior ou snapshot com o controle documentado.
5. Rodar testes de leitura, escrita, fila e jobs em segundo plano.

O check deve guardar identificadores de artefato e snapshot, horários e resultados, mas não credenciais ou dados copiados de clientes. Meça o tempo de recuperação como evidência do seu objetivo operacional, não como promessa universal.

Snapshots só ajudam quando alguém prova que contêm tudo o que o aplicativo precisa. Arquivos, object storage, estado da fila, mudanças de schema e efeitos externos podem ficar fora. Liste esses limites. Um pagamento, e-mail ou webhook já enviado não volta com o restore do banco.

Torne o teste mais forte que um health check. Leia um registro criado antes e outro depois da atualização, altere ambos quando houver compatibilidade e processe um job criado por cada versão. Compare a saída visível, não só códigos. Um servidor que retorna 200 enquanto perde um campo ou interpreta um enum errado não se recuperou.

Teste o controle usado pela pessoa de plantão. Se rollback de produção exige escolher artefato, restaurar snapshot ou trocar tráfego, o ensaio deve usar a mesma interface e permissões. Um script privado no notebook de um engenheiro não é controle operacional. A evidência deve mostrar que o role de operador recupera sem acesso permanente de admin.

Koder.ai suporta exportação de source, deployment e hosting, snapshots e rollback, então aplicativos criados nele podem usar esses artefatos concretos no gate, em vez de deixar a recuperação num parágrafo. A regra é igual em qualquer plataforma: execute o controle e teste o aplicativo restaurado.

Um check obrigatório deve resumir os sete

A decisão final deve exigir um check estável de política que verifique os sete resultados para o head commit exato. Nomes de jobs mudam, matrizes se multiplicam e caminhos opcionais ignoram trabalho. Um pequeno agregador evita que a proteção de branch se afaste da política.

Faça cada gate emitir resultado assinado ou atestado pela plataforma com commit, versão da política, resultado e local das evidências. O agregador rejeita resultados ausentes, antigos, neutros ou cancelados. Ele nunca deduz sucesso de um job que não informou.

{
  "commit": "abc123",
  "policy": "merge-gates-v3",
  "results": {
    "tests": "pass",
    "codeql": "pass",
    "dependency_review": "pass",
    "secret_scan": "pass",
    "authorization": "pass",
    "migration_rehearsal": "not_applicable",
    "rollback_verification": "pass"
  },
  "decision": "allow"
}

Defina um caminho estreito de override para emergências. Exija mantenedor identificado, segundo aprovador, motivo escrito, validade e issue de acompanhamento. O agente não solicita nem aprova a própria exceção. Publique overrides junto aos resultados normais para que continuem visíveis depois do incidente.

Esses checks adicionam minutos a alguns pull requests e muito mais às migrações. É aceitável quando o tempo compra evidência concreta. Rode gates baratos primeiro, cancele commits superados, use cache de entradas confiáveis e reserve o ensaio completo para caminhos relevantes. Não enfraqueça um gate apenas para deixar o painel verde mais cedo.

Comece tornando o comportamento atual observável. Coloque os sete nomes num arquivo de política, conecte cada um a um resultado obrigatório e force o trabalho ignorado a se explicar. O primeiro pull request de agente que não produzir esse registro terá encontrado uma falha na entrega antes que ela chegue à produção.