Codex CLI in GitHub Actions: production-grade CI integration

Running Codex locally makes one developer faster. Running it in CI makes the whole team faster. This guide walks you through wiring Codex into GitHub Actions: four canonical use cases, two auth options, concurrency isolation, caching, and audit guardrails. A reusable workflow template closes the article.

Why put Codex in CI

Local Codex = one user. CI Codex = whole team. Three differences that count:

1. Consistency: every PR passes the same AI review, no more "some PRs reviewed, some not".
2. Audit trail: CI output is auto-archived as artifact, ready for compliance, post-mortem, or replay.
3. Scale: a single machine is one Codex; CI scales to dozens of concurrent review jobs.

The cost is CI complexity: auth, caching, concurrency. We tackle each below.

Scenario matrix: pick the pain you want to solve first

Start with PR auto-review - one file, clear input, high impact. Weekly digest is simplest but easy to deprioritize.

Auth: API key vs OAuth

# Not recommended: API key
env:
  OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}

# Recommended: OAuth device flow
env:
  OPENAI_OAUTH_CLIENT_ID: ${{ secrets.OAUTH_CLIENT_ID }}
  OPENAI_OAUTH_CLIENT_SECRET: ${{ secrets.OAUTH_CLIENT_SECRET }}

API key problem: one secret leak = rotate every key in every repo (the key is account-wide). OAuth device-flow win: short-lived refresh tokens (default 1 hour), per-repo revocable, blast radius is one repo.

OAuth setup is one-time: in the OpenAI console, API Keys → OAuth, create an org-scoped credential, note the client id + secret.

Concurrency isolation

The biggest CI Codex footgun is "two concurrent jobs writing to the same worktree". Three rules:

jobs:
  codex-review:
    runs-on: ubuntu-latest
    # Rule 1: one job per PR at a time
    concurrency:
      group: codex-review-${{ github.event.pull_request.number }}
      cancel-in-progress: true
    steps:
      - uses: actions/checkout@v4
        with:
          # Rule 2: each job gets its own worktree
          ref: ${{ github.event.pull_request.head.ref }}
          fetch-depth: 0

      - name: Install Codex CLI
        run: npm install -g @openai/codex
        env:
          # Rule 3: each job gets its own config dir
          CODEX_HOME: /tmp/codex-${{ github.run_id }}

Three guardrails: concurrency limits one job per PR + checkout to independent worktree + Codex config in a temp dir.

Caching: 90s to 20s

- name: Cache Codex + npm
  uses: actions/cache@v4
  with:
    path: |
      ~/.npm
      ~/.codex
    key: codex-${{ runner.os }}-${{ hashFiles('package-lock.json') }}
    restore-keys: |
      codex-${{ runner.os }}-

• ~/.npm: npm global package cache (Codex CLI installs globally)
• ~/.codex: Codex config cache (OAuth tokens, prompt cache)

Result: second workflow run averages 90s → 20s.

Audit guardrails

Codex in CI carries a "AI breaks the codebase" compliance risk. Three gates:

1. Log trail: every --json Codex output saved as artifact (7 day retention) for incident replay.
2. Human gate: auto-PRs require at least one human approval (branch protection: required_approving_review_count: 1).
3. Token budget: workflow-level MAX_TOKENS cap prevents prompt anomalies from burning tokens.

- name: Run Codex review
  run: codex exec --json "review diff" > codex-output.json
  env:
    MAX_TOKENS: 50000

- name: Upload artifact
  uses: actions/upload-artifact@v4
  with:
    name: codex-review-${{ github.event.pull_request.number }}
    path: codex-output.json
    retention-days: 7

Working template: PR review workflow

name: Codex PR Review

on:
  pull_request:
    types: [opened, synchronize, reopened]

permissions:
  contents: read
  pull-requests: write

jobs:
  codex-review:
    runs-on: ubuntu-latest
    concurrency:
      group: codex-review-${{ github.event.pull_request.number }}
      cancel-in-progress: true

    steps:
      - uses: actions/checkout@v4
        with:
          ref: ${{ github.event.pull_request.head.ref }}
          fetch-depth: 0

      - name: Setup Node
        uses: actions/setup-node@v4
        with:
          node-version: '20'

      - name: Install Codex CLI
        run: npm install -g @openai/codex

      - name: Cache
        uses: actions/cache@v4
        with:
          path: |
              ~/.npm
              ~/.codex
            key: codex-${{ runner.os }}-${{ hashFiles('package-lock.json') }}

      - name: Run Codex review
        id: review
        run: |
          codex exec --json \
            "Review the following PR diff. Focus on: bugs, edge cases, test coverage. Output as JSON with keys: summary, issues[]. Provide line-level comments." \
            < <(git diff origin/${{ github.base_ref }}...HEAD) \
            > codex-review.json
        env:
          MAX_TOKENS: 50000
          OPENAI_OAUTH_CLIENT_ID: ${{ secrets.OAUTH_CLIENT_ID }}
          OPENAI_OAUTH_CLIENT_SECRET: ${{ secrets.OAUTH_CLIENT_SECRET }}

      - name: Post review comment
        uses: actions/github-script@v7
        with:
          script: |
            const fs = require('fs');
            const review = JSON.parse(fs.readFileSync('codex-review.json', 'utf8'));
            const body = [
              '## Codex Review',
              '**Summary**: ' + review.summary,
              '',
              '**Issues**:',
              ...review.issues.map(i => `- ${i.file}:${i.line} - ${i.message}`)
            ].join('\n');
            await github.rest.issues.createComment({
              owner: context.repo.owner,
              repo: context.repo.repo,
              issue_number: context.issue.number,
              body
            });

      - name: Upload artifact
        uses: actions/upload-artifact@v4
        with:
          name: codex-review-${{ github.event.pull_request.number }}
          path: codex-review.json
          retention-days: 7

Swap in your own OAUTH_CLIENT_ID / OAUTH_CLIENT_SECRET and you are live.

Common pitfalls

1. Reusing OAuth tokens across jobs: each job must run its own device flow. Do not cache the refresh token with actions/cache.
2. Diff too large for context: over 500 lines, split into multi-pass review or use git diff --unified=0 to drop context.
3. Codex touches files outside review scope: force read-only with codex exec --readonly to prevent scope creep.
4. Artifacts fill storage: gzip the JSON output (codex-review.json.gz).
5. Prompt has no output format constraint: Codex drifts. Require JSON / table / inline-comment explicitly.

Next steps

• New to Codex locally? Read Getting started with OpenAI Codex CLI: from install to daily use.
• Multi-branch team workflow with worktrees? Read Codex Team Workflow: worktrees, reviews, and CI integration.
• Curious about the model family? Read The complete guide to GPT models (2026-07): GPT-5.6 Sol, Terra, Luna.