Pular para o conteúdo principal

Documentação oficial desta página · v0.20.6

Tutorial: monte um agente de revisão de PR no GitHub

O problema: o seu time abre PRs mais rápido do que você consegue revisar. Os PRs ficam parados por dias esperando um par de olhos. Devs juniores mergeiam bugs porque ninguém teve tempo de conferir. Você passa as manhãs colocando o diff em dia em vez de construir.

A solução: um agente de IA que vigia os seus repositórios o tempo todo, revisa todo PR novo atrás de bugs, falhas de segurança e problemas de qualidade, e manda um resumo — para que você gaste tempo só nos PRs que realmente pedem julgamento humano.

O que você vai montar:

┌───────────────────────────────────────────────────────────────────┐
│                                                                   │
│   Timer do cron ──▶ Agente Hermes ──▶ API do GitHub ──▶ Entrega   │
│   (a cada 2h)       + CLI gh          (diffs de PR)     da revisão│
│                     + skill                             (Telegram,│
│                     + memória                           Discord,  │
│                                                         local)    │
│                                                                   │
└───────────────────────────────────────────────────────────────────┘

Este guia usa jobs de cron para consultar os PRs num horário — sem servidor nem endpoint público. Funciona atrás de NAT e de firewall.

Prefere revisões em tempo real?

Se você tem um endpoint público disponível, dê uma olhada em Comentários automáticos em PR do GitHub com webhooks — o GitHub empurra os eventos para o Hermes no instante em que um PR é aberto ou atualizado.

Pré-requisitos​

  • Hermes Agent instalado — veja o guia de instalação
  • Gateway rodando para os jobs de cron: 
    hermes gateway install   # Instala como serviço
    # ou
    hermes gateway           # Roda em primeiro plano
  • CLI do GitHub (gh) instalada e autenticada: 
    # Instalar
    brew install gh        # macOS
    sudo apt install gh    # Ubuntu/Debian

    # Autenticar
    gh auth login
  • Mensagens configuradas (opcional) — Telegram ou Discord
Sem mensagens? Sem problema

Use deliver: "local" para salvar as revisões em ~/.hermes/cron/output/. Ótimo para testar antes de ligar as notificações.

Passo 1: confira a configuração​

Garanta que o Hermes consegue acessar o GitHub. Abra um chat:

hermes

Teste com um comando simples:

Rode: gh pr list --repo NousResearch/hermes-agent --state open --limit 3

Você deve ver uma lista de PRs abertos. Se isso funcionou, está pronto.

Passo 2: faça uma revisão manual​

Ainda no chat, peça ao Hermes para revisar um PR de verdade:

Revise este pull request. Leia o diff, procure bugs, falhas de segurança
e problemas de qualidade. Seja específico sobre números de linha e cite o código problemático.

Rode: gh pr diff 3888 --repo NousResearch/hermes-agent

O Hermes vai:

  1. Executar gh pr diff para buscar as mudanças de código
  2. Ler o diff inteiro
  3. Produzir uma revisão estruturada com achados específicos

Se você gostou da qualidade, é hora de automatizar.

Passo 3: crie uma skill de revisão​

Uma skill dá ao Hermes diretrizes de revisão consistentes, que sobrevivem às sessões e às execuções de cron. Sem uma, a qualidade da revisão varia.

mkdir -p ~/.hermes/skills/code-review

Crie o ~/.hermes/skills/code-review/SKILL.md:

---
name: code-review
description: Revisar pull requests atrás de bugs, falhas de segurança e problemas de qualidade
---

# Diretrizes de revisão de código

Ao revisar um pull request:

## O que conferir
1. **Bugs** — erros de lógica, erro de um a mais, tratamento de null/undefined
2. **Segurança** — injeção, contorno de autenticação, segredos no código, SSRF
3. **Desempenho** — consultas N+1, laços sem limite, vazamentos de memória
4. **Estilo** — convenções de nome, código morto, tratamento de erro faltando
5. **Testes** — as mudanças têm teste? Os testes cobrem os casos de borda?

## Formato de saída
Para cada achado:
- **Arquivo:Linha** — local exato
- **Severidade** — Crítico / Alerta / Sugestão
- **O que está errado** — uma frase
- **Correção** — como consertar

## Regras
- Seja específico. Cite o código problemático.
- Não aponte implicância de estilo, a menos que atrapalhe a leitura.
- Se o PR está bom, diga isso. Não invente problemas.
- Termine com: APPROVE / REQUEST_CHANGES / COMMENT

Confirme que ela carregou — inicie o hermes e o code-review deve aparecer na lista de skills na abertura.

Passo 4: ensine as suas convenções​

É isso que torna o revisor de fato útil. Abra uma sessão e ensine ao Hermes os padrões do seu time:

Lembre-se: no nosso repositório de backend, usamos Python com FastAPI.
Todo endpoint precisa de anotações de tipo e de modelos Pydantic.
Não permitimos SQL cru — só o ORM do SQLAlchemy.
Os arquivos de teste ficam em tests/ e precisam usar fixtures do pytest.
Lembre-se: no nosso repositório de frontend, usamos TypeScript com React.
Nenhum tipo `any` é permitido. Todo componente precisa de uma interface de props.
Usamos React Query para buscar dados, nunca useEffect para chamadas de API.

Essas memórias ficam para sempre — o revisor vai aplicar as suas convenções sem que você precise repeti-las toda vez.

Passo 5: crie o job de cron automatizado​

Agora junte tudo. Crie um job de cron que roda a cada 2 horas:

hermes cron create "0 */2 * * *" \
  "Procure PRs abertos novos e revise-os.

Repositórios a monitorar:
- minhaorg/backend-api
- minhaorg/frontend-app

Passos:
1. Rode: gh pr list --repo REPO --state open --limit 5 --json number,title,author,createdAt
2. Para cada PR criado ou atualizado nas últimas 4 horas:
   - Rode: gh pr diff NUMERO --repo REPO
   - Revise o diff usando as diretrizes de code-review
3. Formate a saída assim:

## Revisões de PR — hoje

### [repo] #[numero]: [titulo]
**Autor:** [nome] | **Veredito:** APPROVE/REQUEST_CHANGES/COMMENT
[achados]

Se não houver PR novo, diga: Nenhum PR novo para revisar." \
  --name "pr-review" \
  --deliver telegram \
  --skill code-review

Confirme que ele foi agendado:

hermes cron list

Outros horários úteis​

AgendamentoQuando
0 */2 * * *A cada 2 horas
0 9,13,17 * * 1-5Três vezes por dia, só em dias úteis
0 9 * * 1Resumão semanal na manhã de segunda
30mA cada 30 minutos (repositórios de tráfego alto)

Passo 6: rode sob demanda​

Não quer esperar o horário? Dispare na mão:

hermes cron run pr-review

Ou de dentro de uma sessão de chat:

/cron run pr-review

Indo além​

Publicar as revisões direto no GitHub​

Em vez de entregar no Telegram, faça o agente comentar no próprio PR:

Acrescente isto ao prompt do cron:

Depois de revisar, publique a sua revisão:
- Para problemas: gh pr review NUMERO --repo REPO --comment --body "SUA_REVISAO"
- Para problemas críticos: gh pr review NUMERO --repo REPO --request-changes --body "SUA_REVISAO"
- Para PRs limpos: gh pr review NUMERO --repo REPO --approve --body "Ficou bom"
cuidado

Garanta que o gh tem um token com escopo repo. As revisões são publicadas em nome de quem o gh está autenticado.

Painel semanal de PRs​

Crie uma visão geral de todos os seus repositórios na manhã de segunda:

hermes cron create "0 9 * * 1" \
  "Gere um painel semanal de PRs:
- minhaorg/backend-api
- minhaorg/frontend-app
- minhaorg/infra

Para cada repositório mostre:
1. Quantidade de PRs abertos e idade do mais antigo
2. PRs mergeados nesta semana
3. PRs parados (mais de 5 dias)
4. PRs sem revisor atribuído

Formate como um resumo limpo." \
  --name "weekly-dashboard" \
  --deliver telegram

Monitorar vários repositórios​

Cresça acrescentando mais repositórios ao prompt. O agente os processa em sequência — sem configuração extra.

Solução de problemas​

"gh: command not found"​

O gateway roda num ambiente mínimo. Garanta que o gh está no PATH do sistema e reinicie o gateway.

As revisões estão genéricas demais​

  1. Acrescente a skill code-review (Passo 3)
  2. Ensine as suas convenções ao Hermes pela memória (Passo 4)
  3. Quanto mais contexto ele tiver sobre a sua stack, melhores as revisões

O job de cron não roda​

hermes gateway status    # O gateway está rodando?
hermes cron list         # O job está ligado?

Limites de taxa​

O GitHub permite 5.000 requisições de API por hora para usuários autenticados. Cada revisão de PR usa de 3 a 5 requisições (listagem + diff + comentários opcionais). Mesmo revisando 100 PRs por dia você fica bem dentro do limite.

E agora?​