Até aqui, o Codex rodou na sua máquina: no terminal, com o Codex CLI, e dentro do editor, com a extensão. Neste capítulo você vai aprender a usar o Codex na nuvem, isto é, o mesmo agente de programação executando em um ambiente remoto ligado ao seu repositório no GitHub. Ao final, você saberá conectar um repositório, preparar o ambiente com dependências e variáveis, delegar várias tarefas ao mesmo tempo, ler os registros de execução de cada uma, receber pull requests abertos pelo agente e pedir que ele revise os pull requests do seu time.
O que muda quando o agente sai da sua máquina
No uso local, o agente trabalha na sua pasta de trabalho, com os seus arquivos e as suas credenciais. Na nuvem, cada tarefa recebe um ambiente isolado e temporário, um contêiner criado só para ela, com uma cópia do repositório já baixada. O agente lê o código, roda comandos, edita arquivos e, no fim, entrega um diff que você pode transformar em pull request. Quando a tarefa termina, o ambiente é descartado.
Isso traz três consequências práticas. Primeiro, você não fica preso: pode disparar a tarefa e fechar o computador. Segundo, várias tarefas podem correr em paralelo, porque cada uma tem o seu próprio ambiente. Terceiro, e mais importante, o agente só sabe do seu projeto o que estiver no repositório. Se a sua aplicação depende de um banco de dados local, de um arquivo de segredos fora do Git ou de uma variável que só existe na sua máquina, você precisa declarar isso na configuração do ambiente. Caso contrário, os testes vão falhar na nuvem e passar localmente.
Conectando o repositório
O ponto de entrada é o Codex dentro do ChatGPT, na seção própria do agente. Na primeira vez, o serviço pede autorização para instalar o aplicativo do Codex na sua conta ou organização do GitHub. Você escolhe se a permissão vale para todos os repositórios ou apenas para uma lista selecionada. A recomendação é começar com um repositório só, de preferência um projeto pessoal ou um repositório de testes, e ampliar depois.
Em organizações, essa instalação normalmente exige alguém com papel de administrador, e o responsável pelo GitHub da empresa precisa aprovar. Vale conversar com essa pessoa antes, porque a permissão inclui leitura do código e escrita de branches e pull requests. Se a sua empresa tem política de dados, esse é o momento de verificar se o uso está permitido, assunto que o último capítulo retoma.
- Ouça o áudio com a tela desligada
- Ganhe Certificado após a conclusão
- + de 5000 cursos para você explorar!
Baixar o aplicativo
Depois da conexão, cada tarefa começa com três escolhas: o repositório, a branch de origem e o pedido. O pedido segue exatamente a estrutura que você aprendeu no capítulo de prompts, com objetivo, contexto, restrições e critérios de aceitação. E o AGENTS.md do repositório é lido do mesmo jeito, porque ele está versionado junto com o código.
Configurando o ambiente: dependências, variáveis e script de setup
Nas configurações do ambiente do repositório você define como o contêiner é preparado antes de o agente começar. Os três campos que mais importam são a imagem base, com a linguagem e as versões que o projeto usa, o script de setup e as variáveis de ambiente.
O script de setup é um pequeno shell script que roda uma vez, no início, com acesso à rede liberado. É onde você instala dependências e prepara o que a suíte de testes precisa. Um exemplo para uma API em Python:
#!/usr/bin/env bash
set -euo pipefail
python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt -r requirements-dev.txt
# o que é exportado aqui vale só durante o setup;
# persista no shell para que a fase do agente ache o venv
echo "source $(pwd)/.venv/bin/activate" >> ~/.bashrc
# banco de dados de teste em arquivo, sem serviço externo
# (declare DATABASE_URL também no campo de variáveis de ambiente)
export DATABASE_URL="sqlite:///./test.db"
echo 'export DATABASE_URL="sqlite:///./test.db"' >> ~/.bashrc
alembic upgrade head
pytest -q --collect-only
Duas dicas sobre esse script. Termine com um comando barato que prove que o ambiente ficou utilizável, como uma coleta de testes ou uma compilação rápida; assim você descobre problemas de setup antes de gastar uma tarefa inteira. E mantenha o script no repositório, não apenas colado no painel, para que ele evolua junto com o projeto e seja revisado como código. Lembre-se ainda de que o script roda em uma sessão separada: variáveis exportadas nele valem apenas durante o setup, e tudo que os testes precisarem depois deve ser declarado no campo de variáveis de ambiente ou gravado em um arquivo de inicialização do shell, como o ~/.bashrc.
Por padrão, depois do setup o acesso à rede é cortado durante a execução da tarefa. Isso é o mesmo princípio de sandbox que você já conhece, e existe para reduzir o risco de injeção de prompt e de vazamento de dados. Se a tarefa precisa de rede, por exemplo para baixar um pacote novo, libere o acesso conscientemente na configuração do ambiente e, quando possível, restrinja a lista de domínios permitidos.
As variáveis de ambiente têm dois tipos. As comuns ficam visíveis nos registros e servem para coisas como o nome do ambiente ou uma URL de teste. Os segredos do ambiente são valores protegidos, disponíveis apenas durante o setup, indicados para tokens de registro privado de pacotes. Nunca coloque ali a credencial de um sistema de produção. Se uma tarefa realmente exigir isso, ela não deveria rodar em um agente autônomo.
Delegando várias tarefas em paralelo
A vantagem mais concreta da nuvem é o paralelismo. Você pode abrir cinco tarefas independentes em sequência e deixá-las trabalhando enquanto faz outra coisa. Um conjunto típico de manhã:
- corrigir um bug relatado, com teste de regressão;
- gerar testes unitários para um módulo sem cobertura;
- atualizar uma dependência menor e rodar a suíte;
- escrever a documentação de um endpoint recém-criado;
- extrair uma função duplicada em dois arquivos.
A regra de ouro é que as tarefas paralelas não devem tocar nos mesmos arquivos. Se duas delas mexerem no mesmo módulo, você vai receber dois pull requests com conflito e perder no merge o tempo que ganhou na execução. Quando a divisão não é clara, faça a primeira tarefa, integre, e só depois dispare a seguinte a partir da branch atualizada.
Outra prática útil é usar o modo de pergunta para investigação e o modo de código para alteração. Perguntas como um mapa da arquitetura ou o rastreamento do fluxo de uma requisição não precisam gerar diff nenhum, e sair sem diff é um resultado legítimo.
Acompanhando os registros de cada tarefa
Cada tarefa tem uma página com quatro coisas que você deve olhar antes de confiar no resultado. A primeira é o resumo do que foi feito. A segunda é o diff completo, arquivo por arquivo. A terceira é o registro de execução, com os comandos rodados e a saída deles, inclusive o resultado da suíte de testes. A quarta são as citações, isto é, os trechos de arquivo que o agente usou para justificar cada afirmação.
Leia o registro de execução com atenção especial ao final. É comum o agente relatar sucesso quando um teste foi marcado para ignorar, quando a suíte rodou parcialmente ou quando o comando falhou e ele seguiu adiante. Se o registro não mostra a suíte passando, considere que ela não passou.
Do resultado ao pull request
Quando o diff está bom, você pede ao Codex para criar o pull request. Ele empurra uma branch nova para o repositório e abre o pull request com título, descrição do que mudou e um resumo das verificações executadas. A partir daí, tudo é GitHub normal: a sua integração contínua roda, os revisores humanos comentam, as regras de proteção de branch valem.
Duas orientações. Primeiro, peça no próprio prompt o formato da descrição, por exemplo com uma seção de motivação, uma de mudanças e uma de como testar. Segundo, deixe explícito no AGENTS.md o padrão de nome de branch e de mensagem de commit do projeto, porque o agente na nuvem lê esse arquivo e passa a seguir a convenção sem você repetir o pedido.
Você também pode delegar uma tarefa diretamente de uma issue ou de um pull request no GitHub, mencionando o agente em um comentário. É o caminho mais curto quando o contexto do trabalho já está escrito ali.
Revisão automática de pull requests
A outra metade da integração com o GitHub é o Codex atuando como revisor. Há dois modos. No modo sob demanda, alguém escreve um comentário no pull request mencionando o agente e pedindo a revisão. No modo automático, ligado nas configurações de revisão de código do próprio Codex para aquele repositório ou organização, e não nas opções do repositório no GitHub, todo pull request aberto recebe uma revisão assim que é publicado.
A revisão não é uma opinião solta: o agente baixa a branch, lê o código no contexto do repositório inteiro e publica comentários ancorados em linhas específicas, apontando bugs prováveis, casos de borda não tratados, quebras de contrato de API e desvios das regras do projeto. Você pode dirigir o foco no próprio comentário:
@codex review
Foque em: tratamento de erros nas chamadas HTTP e
validação de entrada nos novos endpoints.
Ignore: formatação e nomes de variáveis.
Se encontrar um problema, cite arquivo e linha e proponha o diff.
Trate essa revisão como a de um colega atento, mas falível. Ela erra por excesso, sugerindo mudanças desnecessárias, e por falta, deixando passar problemas de domínio que só quem conhece o negócio percebe. A revisão automática não substitui a aprovação humana; ela limpa o caminho para que o humano gaste atenção no que importa.
Para iterar sobre o feedback, responda no próprio pull request pedindo a correção de um ponto específico. O agente aplica a mudança em um novo commit na mesma branch. Prefira pedidos pontuais, um por vez, a um pedido genérico do tipo resolva todos os comentários, que tende a produzir commits grandes e difíceis de revisar.
Nuvem, local, ou os dois
A tabela abaixo resume as diferenças que mais afetam a decisão do dia a dia.
| Aspecto | Codex local, CLI e extensão | Codex na nuvem |
|---|---|---|
| Onde o código roda | Sua máquina, seus arquivos não versionados | Contêiner temporário, só o que está no Git |
| Tarefas simultâneas | Uma por sessão, atenção contínua | Várias, sem supervisão constante |
| Velocidade de retorno | Imediata, iteração de segundos | Minutos por tarefa |
| Serviços locais e banco real | Disponíveis naturalmente | Só se recriados no setup |
| Entrega | Commit local que você controla | Branch e pull request no GitHub |
| Melhor uso | Depuração fina, exploração, mudanças delicadas | Tarefas bem definidas, em lote, e revisão de pull requests |
O fluxo combinado costuma ser o mais produtivo. Delegue à nuvem o que é bem especificado e verificável por testes, e reserve a sessão local para o que exige conversa, tentativa e erro ou acesso a um ambiente real. Um padrão que funciona bem: a nuvem abre o pull request, você baixa a branch e usa o Codex CLI para ajustar os detalhes finais antes de aprovar.
Recapitulando
Você viu como conectar repositórios ao Codex na nuvem por meio do aplicativo do GitHub, começando por um repositório só. Aprendeu que cada tarefa roda em um ambiente isolado e temporário, e que ele precisa ser preparado com imagem base, script de setup, variáveis comuns e segredos, com acesso à rede liberado apenas quando necessário. Viu como delegar tarefas em paralelo sem criar conflitos, como ler o resumo, o diff, o registro de execução e as citações antes de confiar no resultado, e como transformar o trabalho em pull request com descrição no formato que você definir. Aprendeu a pedir revisão de pull requests sob demanda ou de forma automática, a dirigir o foco dessa revisão e a iterar com pedidos pontuais. E ficou com um critério claro de divisão: nuvem para tarefas bem definidas e em lote, máquina local para o trabalho que pede conversa e ambiente real.
