GitHub Action do Codex

Use a GitHub Action do Codex (openai/codex-action@v1) para executar o Codex em jobs de CI/CD, aplicar patches ou publicar revisões em um fluxo de trabalho do GitHub Actions. A ação instala a CLI do Codex, inicia o proxy da Responses API quando você fornece uma chave de API e executa codex exec com as permissões que você especificar.

Use a ação quando quiser:

• Automatizar o feedback do Codex em pull requests ou lançamentos sem precisar gerenciar a CLI.
• Permitir que as alterações avancem no pipeline de CI somente se passarem nas verificações de qualidade do Codex.
• Executar tarefas repetíveis com o Codex, como revisão de código, preparação de lançamentos e migrações, a partir de um arquivo de fluxo de trabalho.

Para ver um exemplo de CI, consulte Modo não interativo e explore o código-fonte no repositório openai/codex-action.

Pré-requisitos

• Armazene sua chave da OpenAI como um segredo do GitHub (por exemplo, OPENAI_API_KEY) e faça referência a esse segredo no fluxo de trabalho.
• Execute o job em um runner Linux ou macOS. No Windows, defina safety-strategy: unsafe.
• Faça checkout do código antes de executar a ação para que o Codex possa ler o conteúdo do repositório.
• Escolha os prompts que deseja executar. Você pode fornecer o texto diretamente em prompt ou indicar em prompt-file um arquivo já versionado no repositório.

Exemplo de fluxo de trabalho

O fluxo de trabalho abaixo revisa novos pull requests, captura a resposta do Codex e a publica como comentário no próprio pull request.

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
          fetch-depth: 0
          persist-credentials: false

      - name: Run Codex
        id: run_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

  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 }}

Substitua .github/codex/prompts/review.md pelo caminho do seu arquivo de prompt ou use a entrada prompt para fornecer o texto diretamente. O exemplo também grava a mensagem final do Codex em codex-output.md para que você possa consultá-la depois ou enviar o arquivo como artefato.

Configure codex exec

Ajuste a execução do Codex com as entradas da ação que correspondem às opções de codex exec:

• prompt ou prompt-file (escolha apenas uma): forneça as instruções diretamente ou indique o caminho de um arquivo Markdown ou de texto no repositório que descreva a tarefa. Considere armazenar os prompts em .github/codex/prompts/.
• codex-args: aceita opções adicionais da CLI. Forneça um array JSON (por exemplo, ["--ephemeral"]) ou uma string de shell (--profile ci) para configurar sessões, perfis ou parâmetros do MCP.
• model e effort: escolha a configuração do agente Codex. Deixe essas entradas em branco para usar os valores padrão.
• sandbox: escolha o modo de sandbox (workspace-write, read-only, danger-full-access) de acordo com as permissões de que o Codex precisa durante a execução.
• output-file: salve a mensagem final do Codex em disco para que as etapas seguintes possam enviar o arquivo ou comparar seu conteúdo com outra versão.
• codex-version: fixe uma versão específica da CLI. Deixe a entrada em branco para usar a versão publicada mais recente.
• codex-home: indique um diretório base compartilhado do Codex se quiser reutilizar arquivos de configuração ou configurações do MCP em várias etapas.

Gerencie os privilégios

O Codex tem acesso amplo nos runners hospedados pelo GitHub, a menos que você o restrinja. Use estas entradas para controlar o acesso:

• safety-strategy (valor padrão: drop-sudo) remove sudo antes de executar o Codex. A remoção é irreversível durante o job e protege os segredos na memória. No Windows, você precisa definir safety-strategy: unsafe.
• unprivileged-user combina safety-strategy: unprivileged-user com codex-user para executar o Codex com uma conta específica. Verifique se o usuário tem permissão de leitura e gravação na cópia local do repositório (veja como ajustar a propriedade dos arquivos no exemplo de unprivileged-user).
• read-only impede que o Codex altere arquivos ou use a rede, mas ele ainda é executado com privilégios elevados. Não dependa apenas de read-only para proteger segredos.
• sandbox limita o acesso ao sistema de arquivos e à rede dentro do próprio Codex. Escolha a opção mais restritiva que ainda permita concluir a tarefa.
• allow-users e allow-bots restringem quem pode iniciar o fluxo de trabalho. Por padrão, apenas usuários com permissão de gravação podem executar a ação. Liste explicitamente as outras contas confiáveis que deseja autorizar ou deixe o campo em branco para manter o comportamento padrão.

Capture as saídas

A ação disponibiliza a última mensagem do Codex na saída final-message. Associe essa mensagem a uma saída do job, como no exemplo acima, ou processe-a diretamente nas etapas seguintes. Se preferir coletar a transcrição completa do runner, combine output-file com o recurso de envio de artefatos. Quando precisar de dados estruturados, passe --output-schema em codex-args para exigir que a saída siga uma estrutura JSON específica.

Lista de verificação de segurança

• Limite quem pode iniciar o fluxo de trabalho. Prefira eventos confiáveis ou aprovações explícitas a permitir que qualquer pessoa execute o Codex no seu repositório.
• Higienize os dados de pull requests, mensagens de commit ou descrições de issues que serão usados no prompt para evitar injeção de prompt. Revise comentários HTML ou textos ocultos antes de enviá-los ao Codex.
• Proteja sua OPENAI_API_KEY mantendo safety-strategy em drop-sudo ou executando o Codex com uma conta sem privilégios. Nunca deixe a ação no modo unsafe em runners compartilhados entre diferentes clientes.
• Execute o Codex como última etapa do job para que as etapas seguintes não herdem alterações inesperadas de estado.
• Substitua as chaves imediatamente se suspeitar que os logs do proxy ou a saída da ação expuseram informações secretas.

Solução de problemas

• Você definiu prompt e prompt-file ao mesmo tempo: remova uma das entradas para fornecer uma única fonte de instruções.
• O responses-api-proxy não gravou as informações do servidor: verifique se a chave de API está presente e é válida. O proxy só é iniciado quando você fornece openai-api-key.
• Você esperava que sudo fosse removido, mas sudo funcionou: verifique se nenhuma etapa anterior restaurou sudo e se o sistema operacional do runner é Linux ou macOS. Execute novamente em um novo job.
• Erros de permissão após drop-sudo: conceda permissão de gravação antes de executar a ação (por exemplo, com chmod -R g+rwX "$GITHUB_WORKSPACE" ou seguindo o exemplo de unprivileged-user).
• Uma tentativa de execução sem autorização foi bloqueada: ajuste as entradas allow-users ou allow-bots se precisar autorizar contas de serviço além dos colaboradores com permissão de gravação, que já podem executar a ação por padrão.