Automação e CI/CD: Deixando o Codex trabalhar por conta própria na sua ausência

📚 Navegação da série: O artigo anterior 〔26 Integração com Git e GitHub 〕 ensinou como fazer o Codex gerenciar branches, escrever commits e abrir PRs localmente para você — tudo isso com você sentado em frente ao computador e ele trabalhando ao seu lado. Este artigo vai levá-lo ao modo "sem supervisão": depois de configurado, assim que um PR for aberto, o Codex o revisará automaticamente; se o CI falhar, ele proporá um patch de correção automaticamente; e todos os dias em um horário definido, ele gerará um resumo dos commits do dia anterior para você, tudo sem precisar da sua atenção constante. O próximo artigo 〔28 Modo não interativo codex exec 〕 explicará detalhadamente o comando principal por trás de tudo isso.

Dizem que "o maior valor das ferramentas de programação com IA é atuar como seu parceiro em pair programming, escrevendo e conversando ao mesmo tempo" — mas, para ser honesto, isso é apenas meia verdade.

Eu mesmo uso o Codex há mais de meio ano e, quanto mais uso, mais percebo: o lugar onde ele realmente libera a produtividade é justamente quando você não está presente. Naquele modelo de pair programming, você precisa estar lá, monitorando e revisando cada passo. No fundo, ainda é "você liderando e ele ajudando", e se você sai, tudo para. Mas no mundo do código há muitas tarefas chatas e repetitivas — todo PR precisa de uma olhada rápida, se o CI falhar no meio da noite alguém precisa verificar, e toda segunda-feira é preciso preparar um resumo de "o que todos alteraram na semana passada" para o chefe. O ponto comum dessas tarefas é: são repetitivas, seguem padrões, mas ninguém quer ficar fazendo o tempo todo.

Esse tipo de tarefa é o verdadeiro cenário para a automação. Ao integrar o Codex ao fluxo de CI/CD e configurá-lo como uma tarefa agendada, ele deixa de ser "aquele assistente ao seu lado que você precisa vigiar" e passa a ser "aquele que ainda está patrulhando o repositório enquanto você dorme". Este artigo é dedicado especificamente a isso: dois caminhos — um inserindo o Codex no GitHub Actions (no lado do CI/CD), e outro usando as Automations do App desktop para agendar tarefas em segundo plano (no lado da máquina local), cada um cuidando de sua parte. Configurando ambos, seu repositório terá uma camada de automação activa 24 horas por dia.

Ao terminar de ler este artigo, você obterá:

• Uma distinção clara entre os dois caminhos de "automação" — openai/codex-action no CI/CD e as Automations no App desktop para tarefas agendadas em segundo plano, e o que cada um resolve
• Um YAML de workflow do GitHub Actions mínimo e funcional, explicando o que cada linha faz, para que você possa copiar e usar para revisar seus PRs
• Os parâmetros de entrada mais importantes do codex-action que você precisa conhecer (prompt-file, sandbox, safety-strategy, final-message...), todos revisados de acordo com a documentação oficial
• Como configurar a OpenAI key com segurança no GitHub e um limite ainda mais rigoroso do que apenas "não colocar a chave diretamente no código"
• Como configurar as Automations no App desktop, onde ver os resultados das tarefas agendadas e se elas rodam localmente ou em um worktree
• Um tutorial prático com resultados esperados para configurar você mesmo a automação de um "resumo diário"

⚠️ Qualquer referência abaixo a comandos específicos, parâmetros de entrada da action, configurações e valores padrão segue a documentação oficial do Codex (GitHub Action e Automations); números de versão e nomes de modelos que mudam com atualizações devem seguir o que for exibido no seu ambiente local, não sendo fixados neste artigo.

---

01 Distinga primeiro: Existem dois caminhos para a automação, não misture logo no início

Para começar, aqui está o mapa de todo o artigo — a automação do Codex se divide em dois caminhos, rodando em lugares totalmente diferentes e resolvendo dois tipos distintos de tarefas:

• Primeiro caminho: GitHub Action (openai/codex-action). Roda nos runners hospedados pelo GitHub (máquinas na nuvem), acionado por eventos do repositório (abertura de PR, push de código, falha no CI), pertencendo ao lado do CI/CD (Integração Contínua / Entrega Contínua, a sequência de verificações e publicações automáticas antes e depois do código entrar no repositório). Ele faz o trabalho "vinculado à colaboração da equipe": revisar PRs, validar critérios de qualidade e corrigir falhas de CI automaticamente.
• Segundo caminho: Automations (tarefas de automação). Roda na sua própria máquina que está executando o App desktop do Codex, acionado por tempo (agendamento ou ciclos cron), pertencendo ao lado de "tarefas locais em segundo plano". Ele faz o trabalho "vinculado ao seu ritmo pessoal": gerar um relatório diário para você, inspecionar periodicamente um determinado projeto ou monitorar tarefas longas a cada poucos minutos.

Por que precisamos esclarecer essa distinção logo no início? Porque o erro mais comum para iniciantes é aplicar a solução de um caminho aos requisitos de outro — querer que "qualquer pessoa que abra um PR tenha a revisão automática", mas configurar um Automation no App desktop (o que faria a automação parar assim que você desligasse o computador); ou querer que o Codex "me lembre diariamente de verificar esta branch local", mas escrever um workflow do GitHub (o que faria com que ele, na nuvem, não conseguisse acessar seus arquivos locais). Se escolher o caminho errado, a tarefa simplesmente não funcionará.

Analogia: O Guarda da Empresa vs. O Mordomo da Casa. O GitHub Action é como o guarda que você contrata para o "prédio da empresa" (o repositório) — ele não mora na sua casa, mora na guarita do prédio (o runner do GitHub). Sempre que há movimentação no prédio (alguém abre um PR, o CI dispara um alerta), ele entra em ação conforme sua escala de trabalho, controlando o acesso de todos na empresa. Já as Automations são como o mordomo que você contrata para a "sua própria casa" (o projeto local) — ele trabalha diretamente na sua residência (a sua máquina). Você define tarefas como "toda manhã às nove horas organize a lista de entregas de ontem para mim", que é um ritmo puramente privado. Se a sua casa estiver fechada (computador desligado), ele não trabalha. O guarda gerencia os processos de colaboração do prédio público, enquanto o mordomo gerencia suas tarefas privadas agendadas — são duas equipes, dois locais e dois tipos de trabalho, não espere que o guarda receba suas encomendas em casa.

No dia a dia, as tarefas mais adequadas para cada um são as seguintes:

	GitHub Action (codex-action)	Automations (App desktop)
Onde roda	Runners hospedados pelo GitHub (nuvem)	A máquina local onde o App do Codex está aberto
Quem aciona	Eventos do repositório (abrir PR, push, conclusão de CI)	Tempo (agendamento / ciclos cron)
Exige sua presença?	Não, roda sozinho na nuvem	A máquina precisa estar ligada e o App do Codex ativo
Tarefas ideais	Revisar PR, validar critérios de qualidade, auto-correção de falhas de CI	Relatórios diários, inspeções periódicas, monitorar tarefas longas
A qual lado pertence	CI/CD (fluxos de colaboração em equipe)	Tarefas locais em segundo plano

Este artigo segue a ordem "primeiro GitHub Action (seções 02–05), depois Automations (seção 06) e, por fim, prática (seção 07)". Mantenha este mapa em mente para situar cada bloco que explicarmos a seguir.

💡 Resumo em uma frase: A automação tem dois caminhos — o GitHub Action roda na nuvem, é acionado por eventos do repositório e gerencia processos de colaboração de equipe (o guarda); as Automations rodam localmente, são acionadas por tempo e gerenciam tarefas agendadas pessoais (o mordomo); ao escolher um caminho, pense primeiro em "quem deve fazer esse trabalho e onde".

---

02 O que é o GitHub Action: O "pacote pronto para uso" que instala o codex exec no seu fluxo de trabalho

Vamos detalhar o primeiro caminho. Conclusão antecipada: o openai/codex-action é uma GitHub Action oficial criada pela OpenAI. Ela instala a CLI do Codex para você no runner do CI, configura o proxy de comunicação com a OpenAI e executa um comando codex exec sob as permissões que você definir. Você não precisa se preocupar com instalação e login no runner; a action cuida de tudo.

Aqui precisamos reconhecer um termo: codex exec. Trata-se do modo não interativo (non-interactive mode) do Codex — ele não abre aquela interface interativa em tela cheia; você envia um prompt, ele roda, exibe o resultado e encerra, sendo projetado especificamente para scripts e CI. Neste artigo, você só precisa saber: por baixo do capô do GitHub Action roda o codex exec — a action apenas empacota os passos de "instalar a CLI, configurar autenticação e rodar o exec" na nuvem (o próximo artigo 〔28〕 abordará este comando de forma independente).

A definição oficial dele é bem direta:

Use a Codex GitHub Action (openai/codex-action@v1) para executar o Codex, aplicar patches ou postar feedbacks de revisão a partir de um workflow do GitHub Actions em tarefas de CI/CD. A action instalará a CLI do Codex, iniciará um proxy para a Responses API quando você fornecer uma API key e executará o codex exec com as permissões especificadas.

Analogia: A caixa de ferramentas "abrir e usar" para viagens de negócios. Quando você precisa trabalhar no cliente (o runner do GitHub), você pode escolher "carregar um conjunto completo de ferramentas, montando e calibrando cada peça no local" (instalando manualmente o Codex via npm install no runner, configurando a autenticação via codex login e transmitindo a chave com extremo cuidado) — ou pode simplesmente levar uma caixa de ferramentas oficial pronta para uso (codex-action), que ao ser aberta no local já tem a furadeira montada e a tomada conectada (CLI instalada, proxy ativo), restando apenas dizer "fure esta parede" (passar o prompt). O valor desta caixa de ferramentas não está em ser inovadora, mas em resolver para você a tarefa mais propensa a erros: configurar o ambiente com segurança em território alheio — especialmente a parte da "segurança", que detalharemos na seção 05.

A documentação oficial afirma que esta action é ideal para três tipos de tarefas:

• Executar feedbacks automáticos do Codex em PRs ou releases, sem que você precise gerenciar a CLI manualmente
• Bloquear alterações com base nas verificações de qualidade do Codex, servindo como uma etapa de validação no fluxo de CI
• Executar tarefas repetíveis do Codex (revisão de código, preparação de releases, migrações), todas descritas em um arquivo de workflow

Observe um ponto que pode diferir da sua percepção anterior: esse sistema não funciona mencionando o bot com um "@" nos comentários. Ele segue o padrão do GitHub Actions — é acionado por eventos on: definidos no arquivo de workflow (PR aberto, commit enviado, CI concluído). Se você já usou outras ferramentas de IA onde basta escrever um comentário no PR para chamá-la, mude essa expectativa: no caminho do Codex, a IA é integrada diretamente ao fluxo do CI, rodando automaticamente conforme os eventos, sem esperar que você a chame.

💡 Resumo em uma frase: O openai/codex-action é uma "caixa de ferramentas pronta para uso" oficial — ela instala a CLI do Codex no runner de CI, inicia o proxy e executa o comando codex exec por baixo dos panos; ela é acionada por eventos do workflow via on: (não por comentários com @) e é perfeita para revisar PRs, bloquear validações de qualidade e rodar tarefas repetitivas.

Se desenharmos o fluxo geral deste caminho, você terá uma visão muito mais clara:

Este diagrama representa o fluxo completo deste caminho — quando ocorre qualquer um dos três eventos de repositório à esquerda (push, Pull Request, cron agendado), o workflow é acionado; o workflow executa na nuvem o comando não interativo codex exec sob as permissões especificadas; após a execução, ele gera as saídas correspondentes (comentários de revisão no PR, alterações de código sugeridas ou um relatório/resumo). Todo o processo acontece sem a necessidade da sua presença. Lembre-se desta estrutura em três etapas: "quem aciona → onde roda → o que gera", e o preenchimento do YAML seguinte será apenas uma questão de detalhar cada etapa.

---

03 Workflow mínimo: Analisando o YAML oficial de "revisão de PR"

Em vez de ficarmos na teoria, vamos olhar diretamente o workflow funcional fornecido oficialmente — ele faz o Codex revisar automaticamente um PR assim que ele é aberto e colar os comentários de volta no PR. Vou desmembrar o código e traduzi-lo por blocos para que você possa copiar e adaptar para o seu uso.

Analogia: A tabela de "trabalho + entrega" que você faz para os guardas. Este YAML na verdade descreve o trabalho em equipe de dois guardas: o primeiro (job codex) é o guarda de revisão, que entra em serviço assim que o PR é aberto, faz a revisão e anota as observações em um papel (a saída final-message); o segundo (job post_feedback) é o mensageiro, que espera o primeiro terminar de revisar e, se houver observações no papel, cola a nota na seção de comentários do PR. Por que separar em duas tarefas? Você entenderá na próxima seção ao falarmos sobre privilégios — o job de revisão quase não tem permissões (apenas leitura), enquanto o job de envio dos comentários tem permissão de escrita. Essa é uma escolha de design intencional para segurança.

Veja o exemplo completo (simplificado a partir do exemplo oficial, pronto para copiar e adaptar):

# Caminho do arquivo: .github/workflows/codex-review.yml
name: Codex pull request review
on:
  pull_request:
    types: [opened, synchronize, reopened]

jobs:
  codex:
    runs-on: ubuntu-latest
    permissions:
      contents: read
    outputs:
      final_message: ${{ steps.run_codex.outputs.final-message }}
    steps:
      - uses: actions/checkout@v5
        with:
          ref: refs/pull/${{ github.event.pull_request.number }}/merge
          persist-credentials: false

      - name: Run Codex
        id: run_codex
        uses: openai/codex-action@v1
        with:
          prompt-file: .github/codex/prompts/review.md
          output-file: codex-output.md

  post_feedback:
    runs-on: ubuntu-latest
    needs: codex
    if: needs.codex.outputs.final_message != ''
    permissions:
      issues: write
      pull-requests: write
    steps:
      - name: Post Codex feedback
        uses: actions/github-script@v7
        with:
          github-token: ${{ github.token }}
          script: |
            await github.rest.issues.createComment({
              owner: context.repo.owner,
              repo: context.repo.repo,
              issue_number: context.payload.pull_request.number,
              body: process.env.CODEX_FINAL_MESSAGE,
            });
        env:
          CODEX_FINAL_MESSAGE: ${{ needs.codex.outputs.final_message }}

Não se assuste com todo esse bloco, o que realmente pertence ao Codex é apenas aquela pequena parte no meio, o restante é a estrutura padrão do GitHub Actions. Traduzindo por partes:

Primeiro bloco on (quando entrar em serviço): pull_request nos tipos opened (PR recém-aberto), synchronize (novo commit enviado ao PR) e reopened (PR reaberto). Ou seja, sempre que alguém abre um PR ou envia novo código para ele, esta escala de trabalho é ativada.

Segundo bloco checkout (obter o código primeiro): A documentação oficial enfatiza nos "pré-requisitos" — é obrigatório fazer checkout do código antes de chamar a action para que o Codex consiga ler o conteúdo do repositório. Além disso, há o parâmetro persist-credentials: false (para não deixar credenciais Git na área de trabalho) e ref: .../merge (para obter o estado do PR após a mesclagem com a branch de destino para revisão), que são práticas recomendadas padrão para revisão de PRs. (O exemplo original oficial possui uma etapa de Pre-fetch base and head refs entre o checkout e o Run Codex, para buscar previamente as branches base e head do PR; para simplificar a estrutura, nós a removemos aqui. Se você seguir a documentação oficial, verá essa etapa — ela torna o fluxo mais robusto, mas não afeta a compreensão.)

Terceiro bloco Run Codex (núcleo, apenas esta etapa é o Codex):

- uses: openai/codex-action@v1
  with:
    openai-api-key: ${{ secrets.OPENAI_API_KEY }}
    prompt-file: .github/codex/prompts/review.md
    output-file: codex-output.md

Três parâmetros de entrada: openai-api-key transmite a chave (veremos como configurar com segurança na seção 05); prompt-file aponta para um arquivo de prompt salvo no repositório (a recomendação oficial é colocá-lo sob .github/codex/prompts/), descrevendo "como revisar"; output-file salva a mensagem final do Codex no disco para facilitar consultas futuras ou envio como artifact.

Quarto bloco outputs + post_feedback (postar o resultado de volta no PR): O job codex expõe a mensagem final do Codex (steps.run_codex.outputs.final-message) através de outputs; o job post_feedback a recebe usando needs: codex, verifica se há conteúdo real com if: needs.codex.outputs.final_message != '' e usa um script do GitHub para publicá-la como um comentário no PR.

Aqui está o resultado mais importante que você deve memorizar: final-message. A documentação oficial afirma:

A action expõe a mensagem final do Codex através da saída final-message. Você pode mapeá-la como a saída de um job (como mostrado acima) ou processá-la diretamente nas etapas seguintes.

Em termos simples, a final-message é a "nota de observações" que o Codex entrega ao terminar o serviço — você pode usá-la para postar comentários em PRs, enviar no Slack ou usá-la como validação de controle de acesso. O fluxo de dados de todo o workflow é uma linha reta: Codex revisa → resultado vai para final-message → próximo job recebe a saída → posta no PR.

Este diagrama detalha o ciclo de vida do YAML apresentado acima: evento dispara → obtém código → Codex revisa → resultado passa para final-message → se houver conteúdo, posta de volta no PR, com dois jobs trabalhando em sequência.

O prompt deve ser colocado em um arquivo ou escrito na linha? A documentação fornece dois parâmetros alternativos: prompt-file (apontando para um arquivo markdown ou de texto no repositório) ou prompt (um texto em linha direta). Você só pode fornecer um deles, caso contrário a action gerará um erro (mencionaremos isso na seção de solução de problemas na seção 05). Para revisões onde o texto tende a ser longo e você quer controle de versão, usar prompt-file é muito mais prático.

💡 Resumo em uma frase: O workflow mínimo tem apenas uma linha de dados — evento de PR dispara → checkout do código → codex-action revisa conforme prompt-file → resultado vai para final-message → segundo job posta de volta no PR; a única parte que pertence exclusivamente ao Codex são os três parâmetros de entrada de Run Codex, o restante é a estrutura padrão do GitHub Actions.

---

04 Controlando a execução: Os parâmetros de entrada da action que você precisa conhecer

O YAML da seção anterior é a estrutura mínima. Para usá-lo na prática, você precisa saber como ajustar os controles — os parâmetros de entrada do codex-action são basicamente as opções do comando codex exec mapeadas para o YAML. A documentação oficial deixa claro: "Ajuste a execução do Codex configurando as entradas da action correspondentes às opções do codex exec."

Aqui estão os parâmetros mais importantes que os iniciantes devem conhecer primeiro, revisados de acordo com a documentação oficial:

Entrada (input)	O que faz	Observações
prompt / prompt-file	A tarefa designada (linha de texto / arquivo no repositório)	Apenas um pode ser usado, usá-los juntos causa erro
sandbox	Modo de sandbox	workspace-write / read-only / danger-full-access
model e effort	Seleção de modelo e esforço de raciocínio	Deixe em branco para usar o padrão, evite fixar versões específicas
output-file	Salva a mensagem final no disco	Facilita o envio de artifacts ou diffs em etapas posteriores
codex-args	Argumentos extras para a CLI	Array JSON (ex: ["--ephemeral"]) ou string de shell (ex: --profile ci)
codex-version	Fixa uma versão específica da CLI	Deixe em branco para usar a última versão estável lançada
codex-home	Aponta para um diretório home compartilhado do Codex	Útil para reutilizar configurações / MCP entre etapas

Algumas observações importantes sobre itens específicos:

A sandbox é a configuração que você deve pensar com mais cuidado. Na seção 15, detalhamos os três níveis de sandbox — read-only (apenas leitura), workspace-write (escrita na área de trabalho) e danger-full-access (acesso total). No CI, a recomendação oficial é "ajustar o modo sandbox ao nível de permissão estritamente necessário para a tarefa, escolhendo o nível mais restrito possível": se for apenas revisão sem alteração de arquivos, use read-only; se precisar que ele altere o código e envie patches, use workspace-write. O YAML de revisão de PR da seção anterior não especificou sandbox porque a leitura é suficiente.

Aqui está um valor padrão importante que muitas pessoas assumem incorretamente: por padrão, o codex exec roda em uma sandbox apenas de leitura (conforme o texto oficial: "By default, codex exec runs in a read-only sandbox"). Portanto, se o seu workflow precisa que o Codex altere arquivos (como correções automáticas de CI), você deve definir explicitamente sandbox: workspace-write, caso contrário ele não conseguirá gravar. Não assuma que "por estar no CI ele deveria conseguir gravar" — sem essa linha, ele será limitado à leitura.

O codex-args é um "acesso universal de emergência". Qualquer parâmetro que você possa usar localmente com o codex exec pode ser passado por aqui. A documentação oficial aponta um uso comum: para obter saídas JSON estruturadas, passe --output-schema via codex-args (forçando a resposta final do Codex a seguir estritamente um JSON Schema, facilitando o consumo por etapas posteriores). Isso é útil se você quer que o Codex gere, por exemplo, um relatório de riscos com formato fixo para alimentar sistemas downstream.

Deixe model e effort em branco. A documentação indica explicitamente "deixe em branco para usar o padrão". Como modelos e capacidades de esforço mudam rapidamente com as versões, evite fixar modelos específicos no YAML — se realmente precisar especificar, use o modelo ativo na sua conta no momento.

Como essas entradas mapeiam o comportamento do codex exec na prática? Dou um exemplo que aconteceu comigo: na primeira vez que configurei o workflow de revisão, passei apenas o prompt-file sem o output-file. Para ver o que o Codex tinha escrito, eu precisava ler os logs do Actions, que eram longos e bagunçados. Depois que adicionei output-file: codex-output.md e criei uma etapa upload-artifact, pude simplesmente baixar o arquivo markdown limpo após cada execução. Essa é a combinação padrão sugerida oficialmente: salvar via output-file + upload do artifact, caso queira guardar um registro completo.

Um detalhe de segurança relacionado à execução: por padrão, a codex-action iniciará um proxy para a Responses API para transmitir sua OpenAI key (somente quando openai-api-key for fornecida). O objetivo oficial do proxy é minimizar a exposição da chave no runner — e por isso a documentação oficial recomenda fortemente o uso desta action no GitHub Actions em vez de instalar manualmente a CLI e transmitir a chave diretamente.

💡 Resumo em uma frase: As entradas da action são a versão em YAML das opções do codex exec — sandbox define permissões (padrão de apenas leitura, mude para workspace-write se precisar alterar arquivos), prompt/prompt-file são mutuamente exclusivos, model/effort devem ficar em branco para usar o padrão, codex-args serve para passar parâmetros da CLI (como --output-schema) e output-file é usado com upload de artifacts para manter registros.

---

05 Chaves e permissões: A seção mais crítica da automação em CI

A esta altura, você deve ter notado que todo workflow tem uma linha como esta:

openai-api-key: ${{ secrets.OPENAI_API_KEY }}

Esta seção é dedicada especificamente às regras de segurança por trás disso — na automação com CI, este é o lugar mais propício a falhas graves e com custos mais altos. Ela envolve dois aspectos: como armazenar a key e qual o nível de privilégio que o Codex tem no runner.

Regra 1: Salve a key no GitHub Secrets, nunca diretamente no código

A documentação oficial afirma claramente nos pré-requisitos:

Armazene sua OpenAI key como um GitHub secret (por exemplo, OPENAI_API_KEY) e faça referência a ela no workflow.

Por que essa é uma linha vermelha intransponível? Porque os repositórios do GitHub — especialmente os públicos — são visíveis para o mundo inteiro. Se você optar por facilitar sua vida escrevendo a key real diretamente no YAML e enviando-a ao repositório, será equivalente a publicar uma foto da chave da sua casa na internet: crawlers que varrem chaves funcionam ininterruptamente e, se encontrarem sua chave, usarão sua key para consumir a API intensivamente, com a fatura sendo enviada a você.

Analogia: Guardar a chave em um cofre e deixar apenas um código de retirada no YAML. O GitHub Secrets é como um cofre embutido no repositório — você coloca a key real lá dentro, ela é armazenada de forma criptografada e nunca é exibida em logs ou na interface. O código ${{ secrets.OPENAI_API_KEY }} escrito no workflow não é a key em si, mas sim uma instrução: "vá ao cofre e pegue a chave chamada OPENAI_API_KEY para usar". O arquivo pode ser enviado e compartilhado publicamente, pois não contém nenhuma informação sensível real.

Como armazenar no cofre? Acesse Settings → Secrets and variables → Actions no seu repositório, clique em New repository secret, preencha o nome como OPENAI_API_KEY, insira sua key real (obtida em sua conta da OpenAI, como explicado no artigo 04 sobre autenticação) e salve. Depois disso, basta usar ${{ secrets.OPENAI_API_KEY }} no seu workflow para fazer referência a ela.

Regra 2 (Mais rigorosa do que "não expor no código"): Não defina a key como variável de ambiente no nível de job

Muitas pessoas desconhecem este ponto, que inclusive possui um alerta específico na documentação do modo não interativo — indo além do "não expor a chave no código":

Não defina OPENAI_API_KEY ou CODEX_API_KEY como uma variável de ambiente no nível de job em workflows que executam checkout ou rodam código proveniente de repositórios não confiáveis. Scripts de build, testes, hooks de ciclo de vida de dependências ou actions comprometidas no mesmo job podem ler essas variáveis de ambiente.

Em termos simples: mesmo que você não tenha exposto a chave no código e tenha usado o Secrets corretamente, se você a declarar em env: no topo do job (tornando-a visível para todo o job), qualquer script executado ali — como seus testes, scripts executados pelo npm install ou uma action de terceiros maliciosa — poderá capturar sua key facilmente. A prática correta é passar a key apenas para a etapa específica do codex-action (como feito sob with: no exemplo), e não adicioná-la ao bloco env geral do job.

Essa também é a razão pela qual a documentação recomenda repetidamente: "no GitHub Actions, prefira usar o codex-action em vez de instalar a CLI e passar a chave manualmente" — aquele proxy para a Responses API existe justamente para minimizar a superfície de exposição da key.

Regra 3: Controle os privilégios do Codex no runner

A documentação oficial traz uma frase importante: "Nos runners hospedados pelo GitHub, a menos que você a restrinja, a permissão de acesso do Codex é bastante ampla." Ela fornece alguns controles para limitar essa exposição:

Entrada	Função	Padrão / Dica
safety-strategy	Remove privilégios de sudo antes de rodar o Codex para proteger chaves na memória	O padrão é drop-sudo; no Windows deve ser definido como unsafe
unprivileged-user	Configura o codex-user para rodar o Codex sob um usuário específico de baixos privilégios	Este usuário deve ter permissões de leitura/escrita no workspace de checkout
read-only	Impede o Codex de alterar arquivos ou usar a rede	No entanto, ele ainda roda com privilégios altos, não dependa apenas disso para proteger chaves
sandbox	Restringe o acesso ao sistema de arquivos e rede dentro do Codex	Escolha a opção mais restrita que atenda aos requisitos do trabalho
allow-users / allow-bots	Restringe quem pode disparar este workflow	O padrão é que apenas quem possui permissão de escrita pode disparar

Pontos cruciais a serem lembrados:

A safety-strategy padrão é drop-sudo, evite desativá-la. Ela remove os privilégios de sudo antes de rodar o Codex, e essa ação é irreversível para aquele job — servindo como uma barreira de proteção para as chaves no runner. Em runners Windows ela não funciona, exigindo a configuração explícita de safety-strategy: unsafe (como especificado oficialmente), mas a documentação enfatiza: nunca configure a action como unsafe em runners multi-tenant.

read-only não é garantia absoluta de segurança. A documentação alerta: read-only impede que ele altere arquivos ou acesse a rede, mas ele ainda roda com privilégios elevados, "não dependa exclusivamente de read-only para proteger suas credenciais". Para proteger as credenciais, utilize drop-sudo ou contas de usuários com privilégios reduzidos.

allow-users / allow-bots definem "quem pode disparar". Por padrão, apenas usuários com permissão de escrita no repositório podem disparar esta action. Se quiser autorizar contas adicionais confiáveis (como uma conta de serviço específica), adicione-as explicitamente. Em repositórios públicos, esse controle é fundamental — para evitar que qualquer estranho execute o Codex no seu repositório.

Aqui está a lista de verificação de práticas de segurança oficiais resumida para você seguir:

❌ Prática Perigosa	✅ Prática Segura
Escrever a key real diretamente no YAML	Salvar no GitHub Secrets e referenciar no YAML
Definir a key no bloco env geral do job (visível para todo o job)	Passar a chave apenas na etapa específica do codex-action
Usar safety-strategy: unsafe em runners multi-tenant	Manter o padrão drop-sudo ou usar um usuário de baixo privilégio
Permitir que qualquer pessoa dispare o workflow	Utilizar eventos confiáveis, aprovações manuais ou restringir via allow-users
Passar descrições de PR ou commits direto para o prompt	Fazer a limpeza das entradas primeiro para evitar injeções de prompt ocultas em comentários HTML

O último ponto sobre "limpeza das entradas" refere-se à injeção de prompt (prompt injection) abordada no artigo 16 — quando alguém oculta instruções maliciosas direcionadas ao AI na descrição de um PR, mensagens de commit ou no texto de uma issue para induzir o Codex a executá-las. A documentação recomenda explicitamente: antes de passar textos externos ao Codex, verifique se eles contêm comentários HTML ou textos ocultos. O cenário de CI é especialmente vulnerável a isso, pois esses conteúdos podem ser enviados por qualquer pessoa externa. Outra dica prática oficial: execute o Codex como a última etapa de um job, garantindo que as etapas seguintes não herdem estados inesperados que ele possa ter alterado.

💡 Resumo em uma frase: As três camadas de segurança de credenciais em CI são — ① salvar a key no Secrets sem expor no código; ② não defini-la no nível geral de env do job, passando-a apenas para a etapa da codex-action; ③ controlar privilégios e disparadores usando drop-sudo (padrão, mantenha ativo em runners multi-tenant) e allow-users; adicione a isso a limpeza de entradas contra injeções e rodar o Codex no final do job para garantir o uso seguro.

---

06 O outro caminho: Automations do App desktop, agendando uma tarefa em segundo plano

O caminho do GitHub Action foi explicado. Agora vamos voltar e olhar para o segundo caminho — Automations (tarefas de automação), executado no seu App desktop local do Codex, acionado por tempo, para gerenciar tarefas locais em segundo plano.

Para começar, aqui está a conclusão: as Automations servem para fazer o Codex executar periodicamente uma determinada tarefa em segundo plano. Se ao final ele encontrar alguma observação relevante, ela será enviada para a sua caixa de entrada (inbox); caso contrário, a execução será arquivada automaticamente. Como a documentação oficial diz:

Automatize tarefas periódicas em segundo plano. O Codex adiciona descobertas à caixa de entrada (inbox) e arquiva automaticamente a tarefa se não houver nada a reportar.

Analogia: Um alarme no celular de "lembrete agendado + organização automática". Você define um alarme no celular como "lembrar de tomar o remédio às nove da manhã" — ele tocará na hora programada sem que você precise ativá-lo manualmente todos os dias. Mas as Automations são um pouco mais espertas que alarmes: elas não apenas "rodam na hora", mas também avaliam sozinhas se há algo que realmente exija sua atenção — se houver, enviam para a caixa de entrada (como o alarme tocando); se não houver, arquivam silenciosamente (como se percebessem que hoje você não precisa tomar o remédio e preferissem não incomodar). Execução agendada + não perturbar se não houver novidades é a essência das Automations.

O que elas podem fazer: Três cenários reais

Os exemplos oficiais e minha própria experiência mostram que as Automations são ideais para estes três casos:

• Gerar um "resumo diário de atividades do projeto": O exemplo oficial traz uma automação muito útil — "verificar os commits das últimas 24 horas em origin/master ou origin/main, agrupá-los por fluxo de trabalho e escrever um resumo executivo". Eu configurei isso como um Automation toda manhã, o que me dá uma visão clara de "o que foi modificado ontem" antes mesmo de eu começar a trabalhar, sem que eu precise olhar commit por commit.
• Inspeções periódicas: Por exemplo, "fazer uma varredura diária nos meus últimos commits para ver se introduzi bugs e corrigi-los" (há um exemplo oficial completo usando skills, que mencionaremos abaixo).
• Monitorar tarefas longas / consultar estados externos: Para isso, usa-se a "automação de thread" (thread automation), explicada a seguir.

Dois tipos: Tarefa independente vs. Automação de thread

A documentação divide as Automations em duas categorias. Entenda a diferença para não configurar incorretamente:

	Automação independente / de projeto (standalone)	Automação de thread (thread automation)
Cada execução	Inicia uma nova rodada (run) totalmente limpa	Retorna à mesma thread de conversa e continua
Mantém o contexto?	Não, cada execução é independente	Sim, mantém o contexto daquela conversa específica
Para onde vai o resultado	Como uma rodada independente para a caixa de entrada Triage	Fica dentro da própria thread
Mais indicada para	Tarefas que devem ser limpas ou que cruzam múltiplos projetos	Acompanhar um mesmo assunto repetidamente conforme um ritmo definido

A automação independente é ideal para casos como "gerar um novo relatório diário" — onde cada execução é limpa e os resultados são entregues de forma independente na caixa de entrada. A automação de thread funciona como um batimento cardíaco — por exemplo, "monitorar se um comando longo foi concluído" ou "consultar o GitHub a cada poucos minutos sobre o status de um PR e processar novos feedbacks". A cada ativação, ela retorna à mesma conversa com todo o histórico anterior. A documentação alerta: escreva prompts "duráveis" para automações de thread — definindo claramente o que ela deve fazer a cada ativação, como avaliar se há algo a reportar e quando parar ou pedir sua intervenção.

Executar localmente ou no worktree

Para repositórios Git, cada Automation pode ser executada no projeto local ou em um worktree (árvore de trabalho, o mecanismo de múltiplos checkouts do Git abordado no artigo 26) dedicado em segundo plano. A recomendação oficial é clara:

• Modo worktree: Isola as alterações da automação do trabalho que você está fazendo no momento, evitando interferências mútuas — a documentação oficial diz: "use worktree quando quiser isolar as alterações da automação".
• Modo local: Altera diretamente seu checkout principal, podendo modificar arquivos que você está editando no momento. Pense bem antes de usar — a documentação diz: "use o modo local quando quiser que a automação trabalhe diretamente no seu checkout principal, mas lembre-se de que ela pode alterar arquivos que você está editando".
• Projetos sem controle de versão: Executam diretamente no diretório do projeto.

A documentação apenas apresenta os prós e contras sem definir um padrão. Minha recomendação pessoal é: para repositórios Git, use sempre worktree por padrão, evitando que a automação altere arquivos que você está editando durante o dia. No entanto, lembre-se de que muitos worktrees consomem espaço em disco; a documentação oficial alerta que execuções frequentes podem acumular muitos deles, sendo importante arquivar rodadas antigas que não são mais necessárias.

Como criar e como funcionam as permissões

A forma mais simples de criar, segundo a documentação, é pedir diretamente ao Codex em uma conversa comum — "descreva a tarefa, defina a frequência do agendamento, indique se deve rodar na thread atual ou criar uma nova rodada, e o Codex rascunhará o prompt da automação e selecionará o tipo". Você também pode fazer um skill (o sistema de habilidades do artigo 22) criar a automação ou disparar explicitamente um skill usando $nome-do-skill dentro da automação (o exemplo oficial de "corrigir meus bugs automaticamente" consiste em criar primeiro um skill $recent-code-bugfix e agendar um Automation diário para chamá-lo).

Em relação a permissões, há duas regras oficiais cruciais a serem lembradas:

Primeiro: As Automations rodam sob as configurações de sandbox padrão da sua máquina. Se o seu padrão for read-only, as chamadas de ferramentas que alteram arquivos ou acessam a rede falharão — a documentação sugere alterar o padrão para workspace-write se você realmente quer que ela altere arquivos. Por outro lado, se você tiver full access ativado, executar automações em segundo plano sem supervisão é altamente arriscado (ela pode alterar arquivos, rodar comandos e acessar a rede sem perguntar), sendo recomendado limitar ao workspace-write e usar regras (rules) para liberar acessos específicos.

Segundo: As Automations rodam com approval_policy = "never" (quando permitido pelas políticas da sua organização). Ou seja, funcionam sem supervisão e sem exibir caixas de confirmação — o que faz sentido, já que não haverá ninguém na frente da tela para clicar. Mas justamente por isso, a barreira do sandbox se torna ainda mais crítica: como vimos na seção 15, "não perguntar (never)" é diferente de "dar permissão total", e automações em segundo plano exigem a proteção do sandbox. Se a administração proibir approval_policy = "never" via requirements.toml, a automação voltará a exigir confirmações conforme o modo selecionado.

Outra recomendação forte da documentação (e uma armadilha em que já caí): antes de agendar, teste o prompt manualmente em uma conversa comum — para verificar se as instruções estão claras, se o escopo está correto e se o diff gerado faz sentido. Na primeira vez que configurei o "resumo diário", não fiz esse teste prévio. O prompt inicial era muito amplo e a IA gerava uma lista de atividades longa e sem foco; precisei reescrever o prompt três vezes para ajustar. Testar manualmente antes de agendar economiza muitos relatórios inúteis na sua caixa de entrada.

⚠️ Lembre-se do requisito físico: para automações no "escopo do projeto", sua máquina com o App do Codex ativo deve estar ligada, o App em execução e o projeto selecionado salvo no disco no momento programado. Essa é a diferença fundamental em relação ao GitHub Action, que "roda sozinho na nuvem" — o mordomo precisa estar na casa para trabalhar.

💡 Resumo em uma frase: As Automations são tarefas agendadas em segundo plano na máquina local — execução no horário + não incomodar se não houver novidades (descobertas vão para a caixa de entrada, caso contrário são arquivadas); dividem-se em tarefas independentes (novas rodadas) e automações de thread (retornam à mesma conversa); para repositórios Git, recomenda-se usar o modo worktree por padrão para isolamento; rodam com sandbox padrão e approval_policy = "never", portanto teste manualmente antes de agendar e configure o sandbox adequadamente.

---

07 Prática: Configurando um "resumo diário" automatizado com suas próprias mãos

Apenas ler sem praticar não leva ao aprendizado. Vamos agora configurar uma automação agendada mínima no App desktop e validar sua execução. Escolhemos o caminho das Automations para esta prática porque ele não exige permissões de administração nem checkout de repositórios remotos, oferecendo a menor barreira de entrada e resultados rápidos para iniciantes.

Pré-requisitos: Você deve ter o App desktop do Codex instalado (como explicado na seção 07), estar logado e com um projeto local aberto (de preferência um repositório Git para poder testar o modo worktree). Os botões da interface mencionados abaixo podem variar com as updates — siga o que for exibido no seu ambiente real; comandos, campos e comportamentos padrão seguem a documentação oficial.

Etapa 1: Testar o prompt manualmente em uma conversa comum (recomendação oficial forte)

Abra o projeto, inicie uma conversa comum e envie a tarefa que você deseja automatizar para testá-la uma primeira vez. Exemplo:

Verifique os commits deste repositório nas últimas 24 horas e gere um resumo rápido em português:
- Agrupe por tópicos de alteração (não liste commit por commit)
- Use uma ou duas frases para explicar o que foi alterado em cada grupo
- Se não houver commits nas últimas 24 horas, responda apenas: "Sem novos commits nas últimas 24 horas."

Resultado esperado: O Codex lê o histórico do Git e gera um resumo agrupado (ou informa claramente que não houve alterações no período). Esta etapa serve para validar se o prompt está claro e se o resultado atende às suas expectativas. Se o resumo parecer muito longo ou fora do foco, ajuste o prompt ali mesmo e tente novamente — esta etapa é a mais barata para ajustar seu prompt.

Etapa 2: Pedir ao Codex para agendá-lo como uma automação periódica

Com o prompt testado e validado, a forma mais simples é pedir diretamente ao Codex para criar a automação (recomendado oficialmente). Na mesma conversa, diga:

Configure a tarefa de resumo acima como uma automação independente para rodar todos os dias às 9h da manhã,
usando o modo worktree para não alterar meus arquivos locais. Se não houver novos commits, arquive a execução automaticamente sem me notificar.

Resultado esperado: O Codex rascunhará o prompt da automação, selecionará o tipo (independente / standalone), configurará o agendamento para as 9h da manhã e definirá a execução em um worktree. Ele poderá pedir que você confirme alguns detalhes (frequência, escopo); basta clicar em confirmar. Você também pode criar essa automação manualmente na seção de automações na barra lateral do App; o resultado será o mesmo.

Quer um ritmo diferente? O sistema suporta sintaxe cron personalizada — como "toda segunda-feira às 9h". Se precisar de um período específico, selecione agendamento personalizado na criação e insira a expressão cron.

Etapa 3: Confirmar o agendamento na seção de automações

Acesse a seção de automações na barra lateral do App do Codex para verificar.

Resultado esperado: O resumo criado deve aparecer na lista de automações ativas, mostrando seu agendamento (todos os dias às 9h), tipo (independente / standalone) e local de execução (worktree). Ver a automação na lista significa que ela foi agendada com sucesso.

Etapa 4: Disparar manualmente para testar, sem precisar esperar até a manhã seguinte

Não é necessário esperar até as nove horas da manhã do dia seguinte para verificar se está funcionando. Localize a automação na lista e dispare uma execução manual (a documentação oficial recomenda "revisar as primeiras execuções após o agendamento", e disparar manualmente é a forma mais rápida de fazer isso).

Resultado esperado:

• A automação começa a rodar em segundo plano (você poderá acompanhar o status da execução no painel).
• Ao final, se houver commits, a rodada aparecerá na sua caixa de entrada Triage contendo o resumo gerado; se não houver commits nas últimas 24 horas, conforme as instruções do seu prompt, a rodada será arquivada automaticamente e não gerará notificação na caixa de entrada.
• Ver o resumo na caixa de entrada (ou a tarefa ser arquivada corretamente) confirma que todo o fluxo está funcionando.

Etapa 5: Revisar e decidir se vai mantê-la

Abra o resumo gerado na caixa de entrada e leia o conteúdo: avalie se o agrupamento faz sentido, se alguma alteração foi omitida e se a redação está clara. Se encontrar pontos de melhoria, ajuste o prompt da automação (a documentação sugere "revisar os primeiros resultados e ajustar o prompt ou a frequência conforme necessário"). Se decidir que não precisa mais dessa tarefa no futuro, arquive-a — lembrando que, no modo worktree, a documentação oficial recomenda arquivar rodadas antigas para evitar o acúmulo de arquivos temporários de worktree no disco.

Ao seguir essas cinco etapas, você executou o ciclo completo de: testar prompt manualmente → pedir ao Codex para agendar como automação independente às 9h (em worktree) → confirmar no painel → disparar manualmente para testar → revisar os resultados para ajustar ou arquivar. Qualquer tarefa em segundo plano que você configurar no futuro seguirá este mesmo processo, mudando apenas o prompt e o agendamento.

💡 Resumo em uma frase: A prática envolve cinco etapas — testar o prompt em uma conversa comum, pedir ao Codex para agendar a automação diária às 9h em worktree, confirmar no painel lateral, disparar manualmente para testar e revisar o resultado final para ajustar ou arquivar; rodar esse fluxo na prática é mais eficiente do que memorizar qualquer manual de configuração.

---

08 Resumo

Neste artigo, exploramos os dois caminhos de automação do Codex — a integração direta com CI/CD (GitHub Action) e o agendamento de tarefas locais em segundo plano (Automations) no App desktop. Juntos, eles formam uma camada de automação que mantém seu repositório ativo e monitorado mesmo na sua ausência.

Aqui está a recapitulação dos pontos centrais:

Objetivo	Qual caminho usar	Ponto-chave
Compreender os caminhos	Action (nuvem) vs. Automations (local)	Eventos gerenciam colaboração / Tempo gerencia tarefas locais. Não confunda.
Rodar o Codex no CI	openai/codex-action@v1	Executa o codex exec por baixo. Acionado por eventos (não comentários com @).
Entender / Ajustar o workflow	YAML em .github/workflows/	Fluxo de dados: Evento → checkout → revisar → final-message → postar no PR.
Ajustar parâmetros de execução	Parâmetros de entrada da action	sandbox padrão é read-only; mude para write para alterar arquivos; codex-args serve de acesso extra.
Proteger chaves de acesso	GitHub Secrets + Privilégios	Não expor chaves no código, não declarar em env global do job e manter drop-sudo ativo.
Agendar tarefas locais	Automations no App desktop	Execução agendada + não perturbar se não houver novidades. Recomenda-se usar worktree Git.

Agora você é capaz de: identificar claramente quando usar o "GitHub Action para CI/CD" ou as "Automations locais agendadas"; compreender e editar um workflow básico do codex-action, atentando-se para o comportamento padrão apenas de leitura do sandbox; configurar chaves de acesso com segurança no Secrets sem expô-las no env do job; e programar, testar e validar tarefas automatizadas agendadas no App desktop. Dominar essa capacidade de automação é o passo que transforma o Codex de "um assistente de desenvolvimento ao seu lado" em "um integrante da equipe ativo 24 horas por dia nos seus repositórios e rotinas locais".

Com a automação ativa, você não precisa mais gastar tempo com tarefas repetitivas como revisar PRs simples ou preparar relatórios de commits — o guarda e o mordomo estão de serviço, você pode descansar.

---

O próximo artigo 〔28 Modo não interativo codex exec 〕 — como mencionamos repetidamente, tanto o GitHub Action quanto as Automations do App desktop executam por baixo o mesmo comando codex exec. Em outras palavras, o "motor" por trás de toda essa automação é este comando não interativo que recebe um prompt, executa e encerra retornando o resultado. O Action e as Automations são apenas interfaces prontas de encapsulamento para ele. No próximo artigo, abriremos o capô para entender detalhadamente este comando: por que o progresso é exibido em stderr e o resultado em stdout? Como obter fluxos de eventos estruturados em formato JSON com --json? E como usar pipes para integrá-lo com comandos como git, gh ou Slack? Se o Action cuida do acionamento e da execução, entender o codex-exec a fundo é o que permite que você crie seus próprios scripts customizados e defina de onde vêm as entradas e para onde vão as saídas do Codex.

---

Leitura Recomendada

• Sistema de memória (Memories e Chronicle): Fazendo o Codex lembrar de você entre conversas
• Escrita de Prompts: Como falar a língua do Codex
• Extensões para IDE (VS Code e outras)