Revisão de Código Automatizada em 2026: Faça-a Rodar em Todo PR Sem Comprar uma Licença

A revisão automatizada de código é uma tarefa de CI que envia o seu diff para um modelo de linguagem, publica os apontamentos nas linhas afetadas e reprova a verificação de status quando encontra algo grave. A forma de fazer isso rodar em todos os pull requests sem uma assinatura por assento é auto-hospedar uma estrutura de código aberto: copie um workflow de cerca de quinze linhas para o seu repositório, adicione uma chave de API e pague apenas pelos tokens que cada revisão consome. Não há contagem de assentos para comprar, porque não existe assento. A implementação de referência que mantemos é o repositório Orca-Code-Review — público, licenciado sob MIT e, desde a sua criação em 25 de junho de 2026, o código por trás da GitHub Action OrcaCode Review. A receita de roteamento padrão define a etapa de revisão como DeepSeek V4 Flash e o juiz de verificação independente como GLM-5.3, e ambos podem ser alterados por você. Este artigo detalha o que realmente roda em cada push, o que você configura, quanto custa em tokens e os modos de falha que você encontrará na segunda semana.

A versão curta. Cada push recebe uma revisão. Os apontamentos são postados inline nas linhas alteradas. Apontamentos P0 e P1 reprovam o check e bloqueiam o merge; uma execução limpa passa. Você aciona uma nova revisão sob demanda comentando /orcacode-review. O workflow vive no seu repositório; a lógica de revisão vive na action publicada; a escolha do modelo vive em uma receita de roteamento que você pode editar no seu próprio workspace. O revisor lê o diff e os arquivos do repositório e nunca executa o código do seu PR. E a ressalva honesta desde já: ele pega bugs reais e ainda assim perde aqueles que precisam de um humano que saiba por que o código é do jeito que é.

• Um fluxo de trabalho + um segredo + uma conta de token. Sem licença por usuário em nenhum momento.

• O harness é open source. Copie-o, faça um fork, audite-o, fixe-o a um SHA de commit.

• O modelo é uma configuração, não um fornecedor. Altere o revisor editando uma receita de roteamento, não reescrevendo YAML ou ajustando a ação.

• Diffs superdimensionados não custam nada. O guard de tamanho roda antes do modelo.

• Ele lê, nunca executa, o seu código. Essa é a propriedade de segurança que torna o pull_request_target seguro de usar.

Como a revisão de código automatizada realmente funciona

Todo sistema de revisão automatizada é composto pelos mesmos três ingredientes vestindo roupas diferentes: um evento, um executor e um revisor.

O evento é o gatilho. O workflow fornecido é acionado em eventos de pull request — opened, synchronize (um novo push), ready_for_review (um rascunho fica pronto) — e em um comentário de PR. Como ele executa em pull_request_target, a definição do workflow é lida do branch base, e é por isso que o workflow deve existir no branch base antes de poder ser executado para um PR. Uma revisão por push; o concurrency block cancela a execução anterior, de modo que uma sequência rápida de pushes não enfileira cinco revisões de código desatualizado.

O runner é GitHub Actions no ubuntu-latest. O trabalho precisa de três permissões: acesso de leitura ao conteúdo, acesso de escrita a pull requests (para postar comentários inline), e acesso de escrita a issues (para postar o resumo e limpar comentários desatualizados).

O revisor é um modelo de linguagem. A ação busca o head do PR, monta o diff e o contexto do repositório que o mecanismo seleciona, e envia isso para o modelo de revisão. O resultado é um conjunto de achados, cada um marcado com uma severidade e ancorado a um arquivo e uma linha. A ação os publica como comentários inline no PR e escreve um comentário-resumo em uma região de marcadores no topo da descrição do PR, substituído no mesmo lugar a cada push.

O gate é uma verificação de status. O GitHub não sabe o que “review” significa; ele só sabe se o review passa. Você torna o gate real marcando essa verificação como obrigatória na proteção de branch. Esse é todo o mecanismo de bloqueio de merge — sem chamadas de API de admin, sem labels, apenas uma verificação obrigatória com falha.

O que não acontece: nada executa o código do PR. O mecanismo apenas lê. Esse único invariante é o que torna o privilegiado gatilho pull_request_target seguro para usar com uma chave de API paga.

O harness de código aberto é o diferencial.

Tudo acima é verdadeiro para muitas ferramentas. O que não é verdadeiro para a maioria é que tudo é inspecionável e auto-hospedável, que é o que o repositório Orca-Code-Review oferece. É um repositório público do GitHub licenciado sob MIT (JavaScript, criado em 25 de junho de 2026) que empacota a revisão como uma GitHub Action composta reutilizável e um instalador, e é o mesmo código que o aplicativo hospedado OrcaCode Review executa.

Passe dez minutos na árvore e você pode nomear cada parte que toca seu PR:

• action.ymla ação composta, com cerca de quinze inputs documentados. Não há nomes de modelo codificados em lugar nenhum nela.

• workflows/orca-code-review.yml — o workflow de consumidor de exemplo, as aproximadamente quinze linhas que você copia para .github/workflows/.

• recipes/ — o DSL de roteamento. É aqui que o modelo é realmente escolhido.

• rules/ — a rubrica de severidade (P0–P3), o formato de saída obrigatório e uma diretriz de convenções que alimenta a revisão com o documento de convenções do próprio projeto como dados de referência não confiáveis.

• scripts/ — o filtro de precisão (L1 mais um avaliador L2), o guarda de diff, o portão de merge, o relatório de execução e o medidor de tokens. Cada um é um pequeno e legível .mjs arquivo com testes.

• skills/setup-orca-code-review — a skill que o instalador coloca no seu agente de codificação, cobrindo instalação, reconfiguração, solução de problemas e desinstalação.

• .claude-plugin/ — o que permite ao Claude Code instalar a skill como um plugin auto-atualizável.

A instalação é um comando de uma linha que ensina à sua IA o que é o produto e então para:

npx @orcarouter/code-review

A CLI detecta quais agentes de codificação você usa — o catálogo abrange 36 plataformas, de Claude Code, Cursor, Codex, OpenCode e Windsurf a GitHub Copilot, Gem​ini CLI, Amazon Q Developer, Cline, RooCode e outros — instala a habilidade e passa o bastão. Você então pergunta ao seu agente em linguagem simples: “configure o OrcaCode Review neste repositório,” “bloqueie apenas P0,” “por que a revisão não rodou?” A habilidade assume o ciclo de vida: ela escreve o fluxo de trabalho, guia você pelo processo da chave de API, define o gate e faz apenas as perguntas que são realmente suas.

Claude Code pode, em vez disso, instalar a skill como um plugin, o que a mantém atualizada conforme o repositório se move:

/plugin marketplace adicionar Continuum-AI-Corp/orca-code-review

/plugin instalar orca-code-review

Sem nenhum agente? O mesmo ciclo de vida se resume a subcomandos simples — init escreve o fluxo de trabalho, reconfigure altera as regras de bloqueio e os limites de diff, doctor diagnostica revisões que não executam ou não publicam, uninstall remove-o (removendo primeiro a verificação obrigatória). A skill é a porta de entrada, não a única porta. Ou configure manualmente: copie o fluxo de trabalho, adicione um segredo chamado ORCAROUTER_API_KEY, e marque a review como verificação obrigatória.

O motor subjacente é o Open Code Review da Ali​baba, fixado por versão exata e licenciado sob Apache-2.0. OrcaCode decide como revisar; OrcaRouter decide qual modelo o executa. O balanço entre auto-hospedar e hospedar — o que “grátis” realmente custa quando você auto-hospeda um revisor de código aberto — é abordado em nosso artigo sobre revisão de código aberto.

O que é executado, em ordem, a cada push

Ajuda saber a ordem, porque cada etapa pode falhar ou ser pulada de forma independente:

• O guarda de diff roda primeiro, antes do modelo. Se o diff do merge-base exceder 512 KB ou afetar mais de 300 arquivos, a revisão é pulada e um aviso é postado. O padrão é on-oversized-diff: fail, então um diff inflado além dos limites não pode passar por um gate obrigatório sem revisão. Isso também é o controle de gastos: um PR grande demais custa zero tokens.

• O mecanismo revisa o diff. Uma passagem, concorrência por arquivo com padrão de 24 e um teto de tempo real de 20 minutos por passagem.

• O filtro de precisão pós-processa os resultados brutos. L1, um filtro determinístico, verifica o trecho de código existente declarado por cada resultado em relação ao commit revisado e realoca ou descarta incompatibilidades. L2, um avaliador de LLM, agrupa resultados por causa raiz e descarta grupos de baixa confiança. Ambas as camadas são de falha suave: um erro mantém os resultados da etapa anterior e nunca aborta a revisão.

• O gate se aplica. Achados P0 e P1 não passam na verificação; o resumo do PR conta cada achado, incluindo os silenciados no diff.

• O medidor imprime o que custou. O medidor, em sua entrada, registra a contabilidade de tokens por chamada — prompt, conclusão, tokens em cache e o modelo que o roteador resolveu — e imprime uma tabela de totais no log do trabalho.

• Um relatório de execução opcional envia contagens de severidade e metadados de gate ao plano de controle do OrcaRouter para o painel de análises. Ele não contém código, nem diff, nem texto de descoberta.

O que você realmente configura

Há três superfícies, e elas têm raios de explosão muito diferentes.

1. O arquivo do workflow. O workflow consumidor é deliberadamente enxuto. Os inputs que valem a pena alterar estão na action: block-on (quais severidades reprovam a verificação — padrão P0,P1), fix-first (quais severidades interrompem uma revisão exaustiva antecipadamente), auto-review-authors (uma allowlist para quem é revisado automaticamente), max-diff-kb e max-diff-files e on-oversized-diff (a proteção de tamanho), timeout-minutes, concurrency, meter e report. Cada um tem um padrão documentado, então um workflow novo consiste em cinco linhas de YAML mais um segredo.

2. O painel. Com settings: true (o padrão), cada execução busca as configurações por repositório em OrcaRouter → Apps → OrcaCode Review: o modelo, o modo de revisão, a política de merge, as severidades de relatório, o modo silencioso, a revisão exaustiva, uma rubrica personalizada e as salvaguardas. Defina settings: "false" e o arquivo de workflow é autoritativo — nenhum valor do painel pode sobrescrevê-lo. Se você nunca abrir o console, você não perde nada do harness; você apenas configura em YAML.

3. A receita de roteamento — a que passa despercebida. A action nunca nomeia um modelo. Em vez disso, ela injeta fatos brutos como cabeçalhos de requisição — em qual tier a execução foi registrada, se a passagem anterior encontrou um P0/P1, e um marcador de lente quando a requisição é o juiz L2 — e a receita DSL do router do workspace mapeia esses cabeçalhos para um modelo concreto. A receita padrão define o revisor como DeepSeek V4 Flash e o juiz como GLM-5.3, roteando os dois para modelos separados de propósito. Alterar o modelo que revisa seu código é uma edição nessa receita no seu próprio workspace: sem incremento de versão da action, sem reescrever YAML, sem novo deploy.

O contrato de severidade consiste em duas configurações independentes, não uma. Política de merge decide o que bloqueia o merge; relatar severidades decide o que é publicado no diff. Os padrões fornecidos são P0/P1 bloqueiam, P2/P3 passam. Uma severidade que bloqueia é sempre publicada, independentemente do que a configuração de relatório diga — uma verificação que falha sem nada no diff que a explique é pior do que uma ruidosa. P0 significa uma falha de segurança explorável, perda de dados, um travamento em um caminho normal ou um build quebrado; P1 significa um bug real, porém contido; P2 significa um defeito genuíno que só dispara sob uma pré-condição anormal; P3 é estilo. Quando estiver em dúvida entre dois níveis, a regra manda escolher o mais baixo.

Quanto custa

Por token, não por assento. Você escolhe o modelo no OrcaRouter, a cobrança é feita por token consumido, e o medidor torna visível o número por execução em vez de misterioso. A mecânica do GitHub, a revisão de código com medição do Copilot desde 1º de junho de 2026 e como revisores de terceiros se encaixam nesse fluxo de trabalho são abordadas no nosso guia de revisão de código do GitHub. A comparação completa de custos campo a campo — produtos por assento vs. produtos por token, com um exemplo prático — está na nossa comparação de ferramentas de revisão de código com IA, e a questão de quanto custa uma única passada de revisão em tokens quando o revisor de fato explora o repositório (a distinção bot vs. agente) está no nosso artigo sobre agentes de revisão de código. O ponto que este artigo acrescenta é a forma da conta: ela escala com o código que você revisa, não com o número de pessoas que o revisam.

Dois controles de gastos importam no primeiro dia. Em um repositório público, pull_request_target contorna a barreira de aprovação de forks do GitHub, e a chave de revisão é medida por carteira — um estranho pode abrir um PR e disparar revisões pagas. Defina um orçamento de carteira com alertas na chave e defina auto-review-authors para algo como OWNER,MEMBER,COLLABORATOR,CONTRIBUTOR para que contribuidores desconhecidos não sejam revisados automaticamente. E a proteção de diff, como mencionado, significa que PRs excessivamente grandes não custam nada.

O que quebra

Revisão automatizada é CI. Ela quebra como CI, e os modos de falha geralmente não são culpa do modelo:

• O workflow nunca é executado. Para pull_request_target o workflow é lido da branch base — um workflow adicionado apenas na branch do PR não será executado até que a branch seja mesclada. Verifique também se o app está habilitado, se o auto_review está habilitado, se o PR não é um rascunho (rascunhos são ignorados no modo ready_for_review) e se as Actions estão habilitadas no repositório (repositórios bifurcados vêm com elas desativadas).

• /orcacode-review não faz nada. O gatilho do comentário exige que o comentário comece com uma das quatro grafias — /orcacode-review, /orcacode review, @orcacode-review, @orcacode review — e que o comentarista seja um PROPRIETÁRIO, MEMBRO ou COLABORADOR. Um espaço inicial quebra a correspondência. O comando de um contribuidor externo é silenciosamente ignorado, de propósito: o comando executa um fluxo de trabalho privilegiado que detém a chave paga.

• Um erro de autenticação. O segredo está com nome incorreto ou ausente, a chave foi revogada ou está fora do orçamento, ou o fluxo de trabalho foi trocado para pull_request (que não pode ler segredos de forks).

• A verificação está vermelha com um aviso de “diff grande demais”. Isso é o guarda de tamanho, funcionando como configurado. Divida o PR, ou aumente os limites, ou defina on-oversized-diff: pass — e entenda que, com uma verificação obrigatória, pass significa que um PR grande o suficiente passa direto pelo portão sem revisão.

• A revisão é executada, mas nenhum comentário aparece. Três causas, todas benignas ou configuradas: uma execução limpa publica um resumo em vez de comentários inline; o modo silencioso está suprimindo P2 no momento da publicação (o gate e o relatório ainda o contabilizaram); ou o filtro de precisão descartou os achados — L1 descarta achados cujo trecho não corresponde ao commit, L2 descarta clusters de baixa confiança. As contagens de severidade do log do job indicam qual delas.

A postura de segurança merece ser declarada claramente, pois é ela que torna todo o design seguro. O mecanismo apenas lê o diff e os arquivos do repositório; ele nunca executa código de PR. O revisor não tem autoridade de merge — as descobertas podem bloquear um merge ou adicionar um comentário, mas nenhum caminho de código permite que a saída do modelo aprove ou modifique o repositório. Uma descoberta sem etiqueta falha de forma segura, sendo tratada como bloqueante em vez de consultiva. E o relatório de execução não contém código nem texto de descobertas. A configuração em duas camadas, que capta o que uma revisão de passagem única deixa passar, é o tema do nosso artigo sobre segurança na revisão de código com IA; o modelo de ameaças acima está documentado no SECURITY.md do repositório.

Quando a revisão automatizada é a ferramenta errada

Erra com mais frequência do que os fornecedores de ferramentas admitem. Fique de fora quando:

• O problema é contexto, não volume. Se as revisões são lentas porque os revisores precisam entender por que o código foi escrito dessa forma, um LLM lendo o diff acrescenta pouco. Ele não tem memória da discussão do mês passado nem noção do histórico do sistema.

• O diff é, em sua maior parte, código gerado ou de terceiros. Saída autoformatada, arquivos de scaffold, snapshots de dependências. Revisar isso consome tokens e gera ruído, e é exatamente onde a diretriz de convenções menos ajuda — o código não é o estilo do projeto por escolha.

• A equipe já revisa tudo em pares. A revisão automatizada é uma alavanca de volume. Se cada alteração já é revisada por um humano que estava na sala, a máquina acrescenta uma segunda opinião que geralmente é menos informada do que a primeira.

• Ninguém lê os resultados. Uma revisão sobre a qual ninguém age é um fluxo de trabalho que falha verde para sempre. Este é o tipo mais comum de falha silenciosa, e nenhum filtro de precisão o corrige.

• A revisão deve executar o código. Se o que você precisa é de uma suíte de testes contra o PR, uma revisão por LLM é a ferramenta errada. Ela lê; não executa. Uma verificação de segurança que precisa compilar e executar o artefato pertence a uma tarefa separada, com escopo cuidadosamente definido — lembre-se de que o fluxo de trabalho de revisão nunca deve ser estendido para executar código controlado pelo PR.

• O repositório é pequeno ou descartável. Abaixo de um certo ritmo de alterações, a revisão gera mais custo do que os bugs que ela detecta.

Falsos positivos, e o que a filtragem de precisão resolve e não resolve

A acusação contra todo revisor de IA é que ele dá alarme falso. O harness ataca isso em duas camadas, e ajuda a ser preciso sobre qual camada corrige qual falha.

A camada determinística (L1) elimina o achado fantasma: um mecanismo às vezes alega código que não existe — um trecho que se desviou, um achado copiado para um arquivo irmão. A L1 verifica o trecho de código existente de cada achado contra o commit realmente revisado e realoca ou descarta as incompatibilidades. Isso corrige a classe de falso positivo do tipo “esta linha nem existe”, que é mecânica e verificável.

A camada de juiz (L2) elimina a duplicata e a alegação sem suporte: um juiz LLM agrupa os achados por causa raiz e descarta grupos cuja confiança fica abaixo do limite do juiz (padrão 0.5). Isso corrige o “mesmo bug relatado de três maneiras” e o achado especulativo.

O que nenhuma das camadas corrige merece ser dito em voz alta. Um achado errado, mas confiante, sobrevive ao juiz — o juiz é um LLM, e um LLM que parece seguro não é o mesmo que um achado verdadeiro. Um juiz que roda no próprio modelo do revisor concorda consigo mesmo e a validação fica inerte enquanto ainda reporta sucesso, e é por isso que a receita padrão direciona o juiz para um modelo diferente do revisor. E a rubrica de severidade é deliberadamente conservadora — “quando estiver em dúvida entre dois níveis, escolha o mais baixo” — o que significa que um bug real, porém condicional, tem mais probabilidade de cair como um aviso P2 do que como um P1 bloqueante. Essa é a calibração certa para uma ferramenta que não deve bloquear tudo, mas é uma calibração: ela troca bloqueadores perdidos por menos falsos alarmes. O resumo do PR sempre contabiliza todos os achados, então os P2 atenuados ainda estão lá para serem lidos. Se a troca for errada para o seu time, a rubrica e o limite do juiz são configuração, não um chamado de suporte.

O resultado final

Para uma equipe que já vive no GitHub Actions, a ferramenta de código aberto é o caminho mais barato para ter revisão de código automatizada em cada PR: um arquivo de workflow, um segredo, uma fatura de tokens que escala com o código revisado e uma escolha de modelo que é sua. Compre um produto por assento quando você quiser zero operação e um fornecedor para acionar — não porque a revisão é melhor, mas porque você está comprando o problema de outra pessoa em vez de administrar o seu. E antes de configurar qualquer coisa, pergunte se a revisão será lida. A ferramenta pode fazer a revisão acontecer automaticamente. Ela não pode fazer ninguém ler a revisão.

Quer o mesmo revisor sem executá-lo você mesmo? OrcaCode Review executa este exato harness como um GitHub App hospedado — mesma receita aberta, mesma cobrança por token, sem assentos.