Rever pull requests do GitHub com o Codex

Utilize a revisão de código do Codex para obter uma análise adicional de elevado valor nos pull requests do GitHub. O Codex revê o diff do pull request, segue as orientações do seu repositório e publica uma revisão de código padrão do GitHub centrada em problemas graves. A Security Review, disponível como pré-visualização de investigação, proporciona uma análise mais aprofundada de potenciais problemas de segurança num pull request.

Ver: apresentação passo a passo da revisão de código do Codex

Antes de começar

Certifique-se de que tem:

• O Codex cloud configurado para o repositório que pretende rever.
• Acesso às definições de revisão de código do Codex.
• Um ficheiro AGENTS.md, caso pretenda que o Codex siga diretrizes de revisão específicas do repositório.

Configurar a revisão de código do Codex

Para configurar revisões automáticas, necessita de um repositório GitHub ligado e de permissão de push ou de administrador no GitHub para as respetivas definições.

1. Configure o Codex cloud.
2. Aceda às definições do Codex.
3. Ative a Revisão de código para o seu repositório.

Pedir uma revisão do Codex

1. Num comentário de um pull request, mencione @codex review.
2. Aguarde que o Codex reaja (👀) e publique uma revisão.

O Codex publica uma revisão no pull request, tal como faria um colega de equipa. No GitHub, o Codex assinala apenas problemas P0 e P1, para que os comentários da revisão permaneçam centrados nos riscos de prioridade elevada.

Ativar revisões automáticas

Se pretender que o Codex reveja automaticamente todos os pull requests, ative Automatic reviews nas definições do Codex. O Codex publicará uma revisão sempre que alguém abrir um novo PR para revisão, sem necessitar de um comentário @codex review.

Personalizar o que o Codex revê

O Codex procura ficheiros AGENTS.md no seu repositório e segue as regras de revisão de código aplicáveis. Adicione uma secção ## Code Review Rules ao ficheiro mais próximo do código ao qual as regras se aplicam. Utilize títulos ### para agrupar verificações relacionadas quando for útil.

Por exemplo, um serviço de relatórios de experiências pode impedir que o comportamento pós-exposição altere um grupo de comparação:

## Code Review Rules

### Experiment cohorts

- Do not filter treatment comparisons on post-exposure behavior, including conversion or retention.
  Safe path: build cohorts from assignment or exposure; report conversion as an outcome.

Coloque as regras aplicáveis a todo o repositório no ficheiro AGENTS.md da raiz e as regras específicas do serviço num ficheiro aninhado, como services/experiment_reporting/AGENTS.md. O Codex aplica as diretrizes da raiz e as diretrizes mais específicas que abrangem cada ficheiro alterado, para que alterações não relacionadas não tenham de incluir contexto específico do serviço.

Comece com duas ou três regras concisas que codifiquem verificações frequentemente explicadas pelos revisores. Regras úteis:

• Concentre-se em comportamentos importantes e específicos do repositório. Descreva a restrição de compatibilidade, o limite dos dados ou o efeito secundário inseguro a assinalar e por que motivo é importante.
• Indique o percurso seguro ou a exceção. Forneça ao Codex contexto suficiente para distinguir um problema real de um comportamento esperado.
• Mantenha as regras delimitadas e duradouras. Dê preferência aos resultados em vez de nomes de funções que podem mudar e coloque as diretrizes junto do código ao qual se aplicam.
• Deixe as verificações mecânicas no CI. Exclua das regras de revisão a formatação, o lint e outras verificações determinísticas.

Abra um pull request representativo e solicite uma revisão com @codex review. Aperfeiçoe as regras com base nas conclusões e nos comentários que observar e restrinja ou remova as diretrizes que gerem ruído.

As regras de revisão de código orientam o Codex; não substituem testes, proteções de branches nem aprovações obrigatórias.

Para definir um foco pontual, adicione-o ao comentário do pull request:

@codex review for issues in the database migration

Security Review

A Security Review é uma revisão adicional para clientes que pretendem prestar especial atenção a problemas de segurança em pull requests. Analisa os riscos específicos de segurança com maior profundidade do que a Code Review, examinando o diff do pull request, o contexto de apoio do repositório e os modelos de ameaças ou as orientações de segurança configurados.

A Code Review também pode identificar problemas relacionados com segurança no âmbito da sua revisão geral, pelo que poderá existir alguma sobreposição ocasional entre as conclusões da Code Review e da Security Review.

Configurar a Security Review

Para obter instruções de configuração e opções de configuração mais detalhadas, consulte Security Review.

1. Configure o Codex cloud.
2. Aceda às definições do Codex.
3. Em Preferências do repositório, escolha quais os pull requests que recebem uma Security Review e quando esta é executada. Selecione Sempre que a revisão de código for executada para a executar em conjunto com a Code Review.

Pedir uma Security Review

Para pedir manualmente uma Security Review, adicione este comentário a um pull request:

@codex security review

O Codex reage enquanto a revisão está em curso e, em seguida, publica as conclusões de segurança diretamente no pull request. Abra a tarefa do Codex associada e selecione o separador Relatório de segurança para consultar o relatório completo.

Agir com base nas conclusões da revisão

Depois de o Codex publicar uma revisão, pode pedir-lhe que corrija os problemas no mesmo pull request deixando outro comentário:

@codex fix the P1 issue

O Codex inicia uma conversa na cloud com o pull request como contexto e pode enviar uma correção de volta para a branch quando tiver permissão para o fazer.

Atribuir outras tarefas ao Codex

Se mencionar @codex num comentário com algo diferente de review, o Codex inicia uma conversa na cloud utilizando o seu pull request como contexto.

@codex fix the CI failures

Resolver problemas da revisão de código

Se o Codex não reagir nem publicar uma revisão:

• Confirme que ativou Code review para o repositório nas definições do Codex.
• Confirme que o pull request pertence a um repositório com o Codex cloud configurado.
• Utilize o acionador exato @codex review num comentário do pull request.
• Para revisões automáticas, verifique se ativou Automatic reviews e se o evento do pull request corresponde às suas definições de acionamento da revisão.