Revise merge requests do GitLab com o Codex

Use a revisão de código do Codex para obter uma segunda análise dos merge requests do GitLab, com foco nos problemas mais relevantes. O Codex analisa o diff do merge request, segue as orientações do repositório e publica uma revisão de código no formato padrão do GitLab, destacando problemas graves.

A integração de revisão de código com o GitLab está em beta e disponível em todos os planos do ChatGPT. A integração funciona no Codex Cloud. Os controles de repositório do aplicativo para desktop usados com o GitHub, como Criar pull request, não estão disponíveis nesta versão beta.

Se o GitLab aparecer no seletor de repositórios quando você criar um ambiente de nuvem, selecione um projeto do GitLab.com ao qual sua conta conectada tenha acesso. Para tarefas e revisões acionadas pelo GitLab, configure os webhooks conforme as instruções abaixo.

Antes de começar

Verifique se você tem os seguintes itens:

• Uma conta do GitLab conectada. Para o GitLab.com, siga o fluxo de conexão padrão. Para instâncias autogerenciadas ou do GitLab Dedicated, o administrador do espaço de trabalho precisa configurar o modelo de conexão.
• Um arquivo AGENTS.md, caso queira que o Codex siga orientações de revisão específicas do repositório.

Configure a revisão de código do Codex

Configure a conexão com o GitLab e a identidade usada pelo Codex nas revisões

Se você usa o GitLab.com, primeiro conecte o GitLab ao ChatGPT e depois conecte sua conta do GitLab no Codex. Para instâncias autogerenciadas ou do GitLab Dedicated, cada pessoa que faz revisões deve conectar sua conta depois que o administrador do espaço de trabalho publicar o modelo de conexão.

Para instâncias autogerenciadas ou do GitLab Dedicated, abra Codex Cloud → Configurações → Conectores. O administrador do espaço de trabalho pode deixar o Codex criar uma conta de serviço ou salvar o token de acesso pessoal de uma conta de serviço existente.

Deixe o Codex criar a conta

Em Codex Cloud → Configurações → Conectores, selecione o aplicativo do host da sua instância autogerenciada ou do GitLab Dedicated. Em seguida, selecione Configurar conta de serviço → Criar uma conta de serviço. O administrador do espaço de trabalho que concluir a configuração precisa ter acesso de administrador à instância do GitLab. Escolha Grupos selecionados ou Somente projetos selecionados, selecione onde o Codex deve atuar e crie a conta. A primeira opção concede o papel Developer em cada grupo selecionado. Os projetos e subgrupos herdam essa permissão. A segunda opção concede o papel Developer apenas nos projetos que você selecionar. O Codex criará a conta de serviço ChatGPT Codex Connector na instância, com um token de acesso pessoal que tem o escopo api.

Use uma conta existente

No GitLab, crie ou escolha uma conta de serviço e conceda a ela o papel Developer apenas nos grupos ou projetos em que o Codex deve atuar. Na página Contas de serviço, selecione a conta → Gerenciar tokens de acesso → Adicionar novo token para criar um token de acesso pessoal com o escopo api e validade de pelo menos 30 dias a partir da criação. Volte ao Codex, escolha Usar uma conta de serviço existente, cole o token e selecione Salvar token. Ao salvar, o Codex criptografa o token e não volta a exibi-lo.

Gerencie o token da conta de serviço

Os administradores do espaço de trabalho podem gerenciar a conta de serviço em Codex Cloud → Configurações → Conectores. Se o Codex criou a conta, os administradores podem revogar o token atual e gerar outro. Se a conta já existia, eles podem substituir ou remover o token salvo no Codex e, se necessário, revogá-lo separadamente no GitLab. O Codex só pode responder à atividade do GitLab depois que um token válido estiver configurado.

Escolha como o Codex recebe eventos do GitLab

Crie um ambiente de projeto para tarefas de programação ou configurações específicas do projeto

Em Codex Cloud → Configurações → Ambientes, escolha o projeto do GitLab e crie um ambiente para ele quando quiser que o Codex escreva ou execute código nesse projeto, por exemplo, para editar arquivos, fazer commits ou enviar atualizações para a branch de um merge request. Crie um ambiente também quando a revisão depender de segredos, acesso à rede ou comandos de configuração específicos do projeto.

No GitLab.com, você também precisa de um ambiente de projeto para ativar as revisões do Codex.

Ao criar o ambiente, ative Habilitar atividade do GitLab no Codex para instalar o webhook do projeto que envia eventos de merge requests, comentários e issues ao Codex. Para criar o webhook do projeto, você precisa ter o papel Maintainer ou Owner, acesso de administrador ou um papel personalizado com permissão para administrar webhooks de projeto. Webhooks assinados de projetos e grupos exigem o GitLab 19.0 ou posterior. No GitLab 19.0 autogerenciado, confirme se a flag de recurso webhook_signing_token está ativada. Ela vem ativada por padrão nessa versão e foi removida no GitLab 19.1.

Habilite a atividade do GitLab para que o Codex revise os merge requests dos projetos de um grupo e de seus subgrupos

Em instâncias autogerenciadas ou do GitLab Dedicated, os administradores do espaço de trabalho podem abrir Ambientes → Atividade do GitLab → Gerenciar grupos para ativar as revisões do Codex em um grupo e nos seus subgrupos. O Codex instalará um webhook de grupo que abrange todos os projetos desse grupo. O usuário conectado ao GitLab precisa ter o papel Owner no grupo. Os webhooks de grupo exigem o plano GitLab Premium ou Ultimate e a versão 19.0 ou posterior do GitLab.

Habilitar a atividade do grupo permite fazer revisões de código, mas não cria ambientes de projeto. Para executar tarefas de programação acionadas pelo GitLab, como editar arquivos, executar comandos, fazer commits ou enviar atualizações para um merge request, crie um ambiente de projeto.

Configure as políticas de revisão de código

Configure as políticas de revisão de código nas configurações de revisão do Codex. Escolha o repositório e ative Revisão automática em Revisar código. Em Revisão, escolha quais autores terão seus merge requests revisados. Em Gatilho, escolha quando as revisões serão executadas. As configurações do repositório podem substituir suas preferências padrão.

Solicite uma revisão do Codex

1. Em um comentário no merge request, mencione @codex review.
2. Aguarde o Codex reagir com 👀 e publicar a revisão.

O Codex abre discussões e publica notas no merge request do GitLab, como faria alguém da sua equipe. Por padrão, as revisões solicitadas manualmente podem apontar problemas P0, P1 e P2, enquanto as revisões automáticas se concentram em problemas P0 e P1.

Ative as revisões automáticas

Para revisar automaticamente os merge requests que atendem aos critérios, ative Revisões automáticas nas configurações do Codex, escolha a política do repositório do GitLab e selecione um gatilho: Ao abrir o MR, A cada push ou Gatilho inteligente (experimental). Quando o evento do merge request atende aos critérios da política e do gatilho, o Codex executa a revisão sem precisar de um comentário com @codex review.

A atividade do GitLab precisa estar habilitada por meio de um webhook do projeto ou de um grupo acima dele na hierarquia. Em instâncias autogerenciadas ou do GitLab Dedicated, a conta de serviço configurada também precisa ter permissão de escrita no projeto para publicar as respostas. Quando há um ambiente configurado para o projeto, o Codex o utiliza. Se um grupo já tiver a atividade habilitada, os projetos abaixo dele na hierarquia herdarão essa configuração.

Personalize o que o Codex revisa

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

Por exemplo, em um serviço que gera relatórios de experimentos, uma regra pode evitar que o comportamento após a exposição altere a composição de uma coorte de comparação:

## Code Review Rules

### Coortes de experimentos

- Ao comparar tratamentos, não filtre os participantes com base em comportamentos posteriores à exposição, como conversão ou retenção.
  Para evitar esse problema, forme as coortes com base na alocação dos participantes aos grupos ou na exposição ao tratamento. Apresente a conversão como um resultado.

Coloque as regras válidas para todo o repositório no AGENTS.md da raiz e as regras específicas de um serviço em um arquivo de um subdiretório, como services/experiment_reporting/AGENTS.md. Para cada arquivo alterado, o Codex aplica tanto as orientações da raiz quanto as orientações mais específicas que abrangem esse arquivo. Assim, alterações sem relação com o serviço dispensam o contexto específico dele.

Comece com duas ou três regras concisas que registrem as verificações que os revisores costumam explicar. Para escrever regras úteis:

• Concentre-se em comportamentos específicos do repositório que tenham impacto relevante. Descreva a restrição de compatibilidade, o limite de acesso aos dados ou o efeito colateral inseguro que a revisão deve apontar e explique por que isso importa.
• Indique como proceder com segurança ou quando há uma exceção. Dê ao Codex contexto suficiente para distinguir um problema real de um comportamento esperado.
• Defina regras com escopo claro e que continuem válidas ao longo do tempo. Descreva os resultados esperados em vez de citar nomes de funções que podem mudar. Coloque as orientações perto do código ao qual se aplicam.
• Deixe as verificações mecânicas para a CI. Mantenha as verificações de formatação, lint e outras verificações determinísticas fora das regras de revisão.

Abra um merge request representativo e solicite uma revisão com @codex review. Refine as regras com base nos problemas apontados e no feedback recebido. Restrinja o escopo ou remova orientações que gerem comentários irrelevantes.

As regras de revisão de código orientam o Codex, mas não substituem testes, proteções de branch ou aprovações obrigatórias.

Para direcionar uma revisão específica, indique o foco no comentário do merge request:

@codex review procure problemas na migração do banco de dados

Corrija problemas apontados na revisão

Para corrigir os problemas apontados, o Codex precisa de um ambiente de projeto configurado. A atividade do grupo por si só permite revisões, mas não a execução de tarefas de programação. Se o projeto tiver um ambiente, deixe outro comentário no mesmo merge request pedindo ao Codex que corrija um problema:

@codex corrija o problema P1

O Codex inicia um chat de nuvem legado com o merge request como contexto e pode enviar a correção para a branch se tiver permissão.

Atribua outras tarefas ao Codex

Outras tarefas de programação também exigem um ambiente de projeto configurado. A atividade do grupo por si só permite revisões. Se você mencionar @codex em um comentário com uma instrução diferente de review, o Codex iniciará um chat de nuvem legado usando o merge request como contexto.

@codex corrija as falhas de CI

Solucione problemas na revisão de código

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

• Verifique se o aplicativo correto do GitLab está selecionado. Se você usa uma configuração específica do projeto, confirme se ele tem o ambiente esperado no Codex Cloud.
• Confirme se a atividade está habilitada para o projeto ou para um grupo acima dele na hierarquia. No GitLab, acesse Webhooks → Eventos recentes e verifique se os eventos de merge requests e notas foram entregues com sucesso.
• Em instâncias autogerenciadas ou do GitLab Dedicated, confirme se o webhook do projeto ou do grupo está assinado, se a verificação SSL está ativada e se a instância usa o GitLab 19.0 ou posterior. No GitLab 19.0 autogerenciado, confirme se a flag de recurso webhook_signing_token está ativada. Corrija os webhooks desativados automaticamente após falhas.
• Em instâncias autogerenciadas ou do GitLab Dedicated, se você usa uma conta de serviço existente, confirme se o token de acesso pessoal está ativo e tem o escopo api. Se o Codex criou a conta de serviço, confirme se ela está configurada corretamente nas configurações do conector do Codex e se a atividade está habilitada para o projeto ou grupo.
• Em instâncias autogerenciadas ou do GitLab Dedicated, confirme se a conta de serviço do espaço de trabalho tem o papel Developer no projeto ou em um grupo superior para que o Codex possa publicar revisões e reações. Não basta que o usuário conectado ao GitLab tenha esse papel. Os projetos herdam a associação ao grupo. A habilitação da atividade e as permissões da conta de serviço são independentes.
• Confirme se a opção Revisão de código ou Revisões automáticas está habilitada e se o MR atende aos critérios da política e do gatilho do repositório.
• Use @codex review.