Codex GitHub Action

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

Utilize a ação quando pretender:

• Automatizar os comentários do Codex sobre pull requests ou versões sem ter de gerir a CLI.
• Condicionar as alterações a verificações de qualidade orientadas pelo Codex como parte do seu pipeline de CI.
• Executar tarefas repetíveis do Codex (revisão de código, preparação de versões, migrações) a partir de um ficheiro de fluxo de trabalho.

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

Pré-requisitos

• Guarde a sua chave da OpenAI como um segredo do GitHub (por exemplo, OPENAI_API_KEY) e referencie-a no fluxo de trabalho.
• Execute a tarefa num runner Linux ou macOS. No Windows, defina safety-strategy: unsafe.
• Faça checkout do código antes de invocar a ação, para que o Codex possa ler o conteúdo do repositório.
• Decida que prompts pretende executar. Pode fornecer texto diretamente através de prompt ou indicar um ficheiro submetido no repositório com prompt-file.

Exemplo de fluxo de trabalho

O fluxo de trabalho de exemplo abaixo revê novos pull requests, captura a resposta do Codex e publica-a novamente no PR.

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 seu próprio ficheiro de prompt ou utilize a entrada prompt para fornecer texto diretamente. O exemplo também grava a mensagem final do Codex em codex-output.md para inspeção posterior ou carregamento como artefacto.

Configurar codex exec

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

• prompt ou prompt-file (escolha uma): instruções diretas ou um caminho do repositório para um ficheiro Markdown ou de texto com a sua tarefa. Considere guardar os prompts em .github/codex/prompts/.
• codex-args: parâmetros adicionais da CLI. Forneça uma matriz JSON (por exemplo, ["--ephemeral"]) ou uma cadeia de shell (--profile ci) para configurar sessões, perfis ou definições de MCP.
• model e effort: escolha a configuração do agente Codex pretendida; deixe em branco para utilizar os valores predefinidos.
• sandbox: ajuste o modo de sandbox (workspace-write, read-only, danger-full-access) às permissões de que o Codex necessita durante a execução.
• output-file: guarde a mensagem final do Codex no disco, para que os passos posteriores possam carregá-la ou compará-la.
• codex-version: fixe uma versão específica da CLI. Deixe em branco para utilizar a versão publicada mais recente.
• codex-home: indique um diretório inicial partilhado do Codex caso pretenda reutilizar ficheiros de configuração ou configurações de MCP entre passos.

Gerir privilégios

O Codex dispõe de acesso abrangente em runners alojados no GitHub, a menos que o restrinja. Utilize estas entradas para controlar a exposição:

• safety-strategy (predefinição: drop-sudo) remove sudo antes de executar o Codex. Esta operação é irreversível durante a tarefa e protege os segredos em memória. No Windows, tem de definir safety-strategy: unsafe.
• unprivileged-user associa safety-strategy: unprivileged-user a codex-user para executar o Codex com uma conta específica. Certifique-se de que o utilizador pode ler e escrever no checkout do repositório (consulte o exemplo de unprivileged-user para corrigir a propriedade).
• read-only impede o Codex de alterar ficheiros ou utilizar a rede, mas este continua a ser executado com privilégios elevados. Não confie apenas em read-only para proteger segredos.
• sandbox limita o acesso ao sistema de ficheiros e à rede no próprio Codex. Escolha a opção mais restrita que ainda permita concluir a tarefa.
• allow-users e allow-bots restringem quem pode acionar o fluxo de trabalho. Por predefinição, apenas os utilizadores com acesso de escrita podem executar a ação; indique explicitamente outras contas fidedignas ou deixe o campo vazio para manter o comportamento predefinido.

Capturar resultados

A ação disponibiliza a última mensagem do Codex através da saída final-message. Associe-a a uma saída da tarefa (como mostrado acima) ou processe-a diretamente em passos posteriores. Combine output-file com a funcionalidade de carregamento de artefactos se preferir recolher a transcrição completa do runner. Quando necessitar de dados estruturados, transmita --output-schema através de codex-args para impor uma estrutura JSON.

Lista de verificação de segurança

• Limite quem pode iniciar o fluxo de trabalho. Dê preferência a eventos fidedignos ou aprovações explícitas, em vez de permitir que qualquer pessoa execute o Codex no seu repositório.
• Sanitize as entradas de prompts provenientes de pull requests, mensagens de commit ou conteúdos de problemas para evitar a injeção de prompts. Reveja comentários HTML ou texto oculto antes de os fornecer ao Codex.
• Proteja o seu OPENAI_API_KEY mantendo safety-strategy em drop-sudo ou transferindo o Codex para um utilizador sem privilégios. Nunca deixe a ação no modo unsafe em runners multi-inquilino.
• Execute o Codex como último passo de uma tarefa, para que os passos posteriores não herdem alterações de estado inesperadas.
• Substitua imediatamente as chaves se suspeitar que os registos do proxy ou a saída da ação expuseram material secreto.

Resolução de problemas

• Definiu simultaneamente o prompt e o ficheiro de prompt: remova a entrada duplicada para fornecer exatamente uma origem.
• O responses-api-proxy não gravou as informações do servidor: confirme que a API key está presente e é válida; o proxy só é iniciado quando fornece openai-api-key.
• Esperava que sudo fosse removido, mas sudo foi concluído com êxito: certifique-se de que nenhum passo anterior restaurou sudo e de que o sistema operativo do runner é Linux ou macOS. Volte a executar com uma nova tarefa.
• Erros de permissão após drop-sudo: conceda acesso de escrita antes de a ação ser executada (por exemplo, com chmod -R g+rwX "$GITHUB_WORKSPACE" ou utilizando o padrão de utilizador sem privilégios).
• Acionamento não autorizado bloqueado: ajuste as entradas allow-users ou allow-bots se necessitar de permitir contas de serviço para além dos colaboradores com acesso de escrita predefinidos.