Running Codex in CI with the Codex GitHub Action

Who this is for

This is for readers who already host code on GitHub and want Codex to review pull requests or run fixed tasks in CI, without installing and calling the CLI by hand in every job. By the end you can write a workflow that runs Codex when a pull request is opened or updated, and posts the result back to the PR.

What the Codex GitHub Action is

The Codex GitHub Action (openai/codex-action@v1) runs Codex inside a GitHub Actions job. It installs the Codex CLI, starts the Responses API proxy when you provide an API key, and runs codex exec under the permissions you specify.^[1] The action handles installation, key handling and permission settings, so the workflow only has to declare its inputs.

OpenAI lists three kinds of use: automating Codex feedback on pull requests or releases, gating changes on Codex-driven quality checks in CI, and running repeatable tasks such as code review, release prep and migrations from a workflow file.^[1]

Prerequisites

1. Store your OpenAI key as a GitHub secret, such as OPENAI_API_KEY, and reference it in the workflow.^[1]
2. Run the job on a Linux or macOS runner. On Windows, set safety-strategy to unsafe.^[1]
3. Check out the code before the action runs, otherwise Codex cannot read the repository contents.^[1]
4. Choose where the task comes from. prompt takes inline text, and prompt-file takes a file committed to the repository. Use one or the other; the troubleshooting guide asks you to remove the duplicate input if both are set.^[1]

A pull request review workflow

The sample below is the first job of the official example. It runs when a pull request is opened, updated or reopened, reads its prompt from .github/codex/prompts/review.md, and writes Codex's final message to codex-output.md.^[1] The sample's second job uses actions/github-script to post that message back on the pull request as a comment.^[1]

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

A few points to note:

• The types list limits the trigger to opened, synchronize and reopened.^[1]
• output-file saves the final message to disk, so later steps can upload or compare it.^[1]
• The final-message output carries the last Codex message. The sample passes it to the next job through outputs.^[1]

Before using this in a real repository, point prompt-file at your own prompt file.^[1]

Action inputs

• prompt or prompt-file: pick one.
• codex-args: extra CLI flags. It takes a JSON array such as ["--ephemeral"], or a shell string such as --profile ci. For structured output, pass --output-schema through it.^[1]
• model and effort: choose the Codex agent configuration. Leave them empty for defaults.^[1]
• sandbox: one of workspace-write, read-only or danger-full-access. Pick the narrowest one that still lets the task finish.^[1]
• output-file: saves the final message to disk.^[1]
• codex-version: pins a CLI release. Leave it blank to use the latest published version.^[1]
• codex-home: points to a shared Codex home directory, so several steps can reuse configuration files or MCP setups.^[1]

Permissions: narrow them first

On GitHub-hosted runners Codex has broad access unless you restrict it, so the permission inputs matter.^[1]

• safety-strategy defaults to drop-sudo, which removes sudo before Codex runs. The docs say this is irreversible for the job, and that it protects secrets held in memory.^[1]
• To run as a named account, use safety-strategy: unprivileged-user together with codex-user. That account must be able to read and write the repository checkout. The docs link an example, examples/unprivileged-user.yml, that shows the setup.^[1]
• read-only stops Codex from changing files or using the network, but it still runs with elevated privileges, so it should not be the only protection for secrets.^[1]
• allow-users and allow-bots decide who can trigger the workflow. By default only users with write access can run the action.^[1]

Security checklist

• Text from pull requests, commit messages or issue bodies can carry prompt injection. Sanitize it before it reaches Codex, and check for HTML comments and hidden text.^[1]
• Do not leave the action in unsafe mode on multi-tenant runners.^[1]
• If the proxy logs or the action output may have exposed a key, rotate that key immediately.^[1]
• Put the Codex step last in the job, so later steps do not inherit unexpected state changes.^[1]

Common errors

• **Both prompt and prompt-file are set**: remove one of them.^[1]
• responses-api-proxy didn't write server info: the proxy starts only when openai-api-key is provided. Check that the key exists and is valid.^[1]
• **Permission errors after drop-sudo**: grant write access before the action runs, for example with chmod -R g+rwX "$GITHUB_WORKSPACE", or switch to the unprivileged-user pattern.^[1]
• An unauthorized trigger is blocked: adjust allow-users or allow-bots.^[1]

Next steps

The action's source code and more examples are in the openai/codex-action repository on GitHub.^[2]