The Codex GitHub Action: PR Reviews and Quality Gates

OpenAI ships an official GitHub Action for Codex: it installs the CLI on the runner, runs your prompt non-interactively, and hands the result back to the workflow. Setup is one repository secret (OPENAI_API_KEY) plus a few lines of YAML, and a merge gate is the same workflow marked as a required status check. Billing is per token against your OpenAI platform account, which is the right shape for shared CI even when it is not the cheapest one.

What the action is, and what it is not

The action (github.com/openai/codex-action) is the run-it-in-your-runner variant of Codex automation: your workflow, your compute, your API key. It is not the same thing as Codex’s cloud code review, which you enable from the ChatGPT side and which bills to your plan. People conflate the two because both can end with a review comment on a PR. The distinction that matters is who runs the agent and which bill it lands on.

If you want raw codex exec steps without the action wrapper, the CI/CD guide builds the same pipeline by hand. The action saves you the install-and-auth boilerplate and adds structured inputs and outputs; underneath, both routes run the CLI’s documented non-interactive mode, covered in the codex exec guide.

Setup: one secret, one workflow

1. Create an API key at platform.openai.com, scoped to its own project so the spend is visible in isolation.
2. Add it as a repository secret named OPENAI_API_KEY (Settings, then Secrets and variables, then Actions).
3. Commit a workflow:

name: codex
on:
  pull_request:

jobs:
  review:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - uses: openai/codex-action@v1
        with:
          openai-api-key: ${{ secrets.OPENAI_API_KEY }}
          prompt: "Review the changes in this PR for bugs and risky patterns. Be specific: file, line, problem, suggested fix."

Input and output names come from the action’s README at github.com/openai/codex-action; check it when you pin a new version, since the surface can grow between releases. fetch-depth: 0 matters for any review prompt that diffs against the base branch. And treat the action like any third-party dependency in a workflow that holds secrets: pin a release you have read the notes for, and bump it deliberately rather than tracking a moving tag.

The PR review recipe

A review nobody sees is a review that did not happen, so post the result back to the PR:

name: codex-review
on:
  pull_request:

permissions:
  contents: read
  pull-requests: write

jobs:
  review:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - uses: openai/codex-action@v1
        id: codex
        with:
          openai-api-key: ${{ secrets.OPENAI_API_KEY }}
          prompt: |
            Review the diff between origin/main and HEAD.
            Flag bugs, missing tests, and security issues with file and line.
            End with exactly one line: VERDICT: PASS or VERDICT: FAIL.

      - name: Comment on the PR
        env:
          GH_TOKEN: ${{ github.token }}
          REVIEW: ${{ steps.codex.outputs.final-message }}
        run: |
          printf '%s\n' "$REVIEW" > review.md
          gh pr comment "${{ github.event.pull_request.number }}" --body-file review.md

Two details earn their place. The review text travels through an environment variable and a file, never interpolated directly into the shell line, so a review containing backticks or quotes cannot break (or become) the command. And the prompt pins an output contract, the VERDICT: line, which the next section turns into a gate.

Gating merges on the Codex check

Add one step after the review:

      - name: Gate on the verdict
        env:
          REVIEW: ${{ steps.codex.outputs.final-message }}
        run: grep -q "VERDICT: PASS" <<<"$REVIEW"

Then make it binding: repository Settings, then Branches, then your protection rule for main, then require status checks and select the review job. From that point, a failing Codex verdict blocks the merge button exactly like a failing test suite.

Run the gate in advisory mode first. Leave the comment step on and the grep step off for a week or two, and read what Codex flags. Agent reviewers are reliable on concrete defects, unhandled errors, missing tests, obvious injection risks, and unreliable on architectural intent. Gate on narrow, checkable instructions (“flag any new endpoint without an auth check”), keep taste in human review, and the false-positive rate stays low enough that nobody learns to click past the check. A quality gate only works if people trust it enough to leave it on.

What it costs

The action bills two meters: GitHub Actions minutes and OpenAI API tokens. Token cost scales with diff size and how hard the model has to think, so per-review numbers vary too much to quote honestly; OpenAI’s platform pricing page has current rates. The controls that work: scope the key to its own project with a monthly budget, keep fetch-depth honest but prompts focused on the diff, and skip draft PRs with an if: !github.event.pull_request.draft condition. Per-repo spend caps and request logs for CI keys are what our GitHub Actions integration handles.

Why an API key and not your ChatGPT plan

Anyone with write access can trigger a shared workflow, so the credential behind it must be impersonal and revocable. An API key is both; a ChatGPT session is neither, and OpenAI’s terms tie each account to a single user. That is why the action documents key auth, and the full reasoning, including the patterns that do get you plan pricing for CI-shaped work, is in can GitHub Actions use your ChatGPT plan?

The short version: metered review jobs in shared CI are the clean spend. Your own bulk automation, the agents and batch jobs that run on your behalf, is where flat plan pricing belongs. We built Codex Hosted for exactly that half: your ChatGPT account signed in to an isolated container we keep running, exposed as an OpenAI-compatible endpoint your workflows can call with a revocable key.