CI Auth & the GitHub Action

Interactively, you are the guardrail — Codex pauses and you approve. In CI there is no human in the loop, so two things change at once: the agent runs unattended, and it runs with a long-lived credential sitting in the environment. Get either wrong and a single prompt-injected file or a malicious dependency can read your key and exfiltrate it, or the agent can wander outside the work you intended.

So every decision in this lesson reduces to two questions:

1. Which credential, and how narrowly is it scoped? Prefer a key that only one command can see, over one exported process-wide.
2. How little power can the run get away with? Least-privilege sandbox, least-privilege OS user, least-privilege GitHub token.

Keep those two levers in mind and the rest is detail. The dossier's one-line summary is worth memorizing: "sandboxing is used to prevent the model from making harmful changes that might be the result of a prompt injection" — and the same instinct applies to the credential itself.

Codex offers ChatGPT-account sign-in OR API-key sign-in everywhere, and CI is no exception. The trade-off is billing and simplicity:

For most CI, the API-key path is simpler and the documented recommendation — there is no file to refresh and no per-runner state. Reach for the ChatGPT token path only when you specifically want CI to draw on a plan's included allowance rather than billing API usage.

Because model names, prices, and per-plan limits change constantly, don't hard-code which is cheaper — check the live pricing page when you decide.

There are two relevant env vars, and the distinction is the whole point:

• OPENAI_API_KEY — the general OpenAI key, honored broadly.
• CODEX_API_KEY — honored only by codex exec (the non-interactive entry point). The docs recommend setting it for the single codex exec invocation so that no other code in the job can read it.

That second variable exists specifically for CI safety. The pattern is to set it inline on the command, not export it for the whole job:

# GOOD: the key is only in the environment of this one process
CODEX_API_KEY="$OPENAI_KEY_SECRET" codex exec --json \
  --sandbox workspace-write \
  "Fix the failing unit tests and explain the change"

Contrast that with exporting it job-wide:

# RISKIER: every step (and any tool/dependency it runs) can read the key
env:
  OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}

When Codex runs untrusted code — installing dependencies, running a build script a malicious PR modified — anything in the process environment is readable. Inline-scoping the key shrinks that window to a single command. (OPENAI_API_KEY is still fine when you control the workflow and the repo is trusted; the inline CODEX_API_KEY pattern is the belt-and-suspenders version for untrusted input.)

To use ChatGPT-account auth in CI, you store a previously-generated auth.json in a secret and write it onto the runner at the start of the job. Two non-obvious requirements make this work:

1. The token must land in a plaintext file, not the OS keychain — so you need cli_auth_credentials_store = "file" in config.
2. Codex auto-refreshes the token (when it is ~8 days old or a request returns 401) and writes the new token back to auth.json. That write-back is the gotcha.

Seeding the file:

mkdir -p "$CODEX_HOME"; chmod 700 "$CODEX_HOME"
printf '%s' "$CODEX_AUTH_JSON" > "$CODEX_HOME/auth.json"
chmod 600 "$CODEX_HOME/auth.json"

($CODEX_HOME defaults to ~/.codex. The file is plaintext access/refresh tokens — treat it like a password: never log it, never echo it, lock the file mode down.)

The refresh behavior dictates two rules depending on runner type:

Sometimes you need to log in on a box with no browser — a headless server, a container, a remote runner you're provisioning. The normal codex login opens a browser for OAuth, which won't work there. Two documented options:

• codex login --device-auth — prints a one-time code you enter on another device's browser. The classic headless flow.
• SSH-forward the localhost callback. Normal login spins up a local callback listener on port 1455; forward that port over SSH so the OAuth redirect on your laptop reaches the listener on the remote host.

# Forward the OAuth callback port from the remote box to your laptop
ssh -L 1455:localhost:1455 user@remote-host
# then, on the remote host:
codex login          # opens the callback on :1455, which you reach locally

Other auth subcommands worth knowing for scripted setup: codex login --with-api-key (key via stdin), codex login --with-access-token (token via stdin), and codex login status (exits 0 when logged in — handy as a CI precondition check). Because these flags evolve, confirm against https://developers.openai.com/codex/auth.

Whichever method you use, the result is the same ~/.codex/auth.json you'd seed directly — device-auth and port-forwarding are just ways to produce that file on a machine without a browser.

Rather than scripting codex exec yourself, the official openai/codex-action@v1 installs the CLI, starts a Responses-API proxy when you give it an API key, and runs codex exec under a configurable safety strategy. It runs on Linux and macOS runners; Windows requires safety-strategy: unsafe.

The inputs map almost one-to-one onto the exec flags you already know:

The Action exposes one output, final-message (the final codex exec message), which you map to a job output for downstream steps. A minimal PR-review job:

name: Codex pull request review
on:
  pull_request:
    types: [opened, synchronize, reopened]

jobs:
  codex:
    runs-on: ubuntu-latest
    permissions:
      contents: read          # least-privilege token
    outputs:
      final_message: ${{ steps.run_codex.outputs.final-message }}
    steps:
      - uses: actions/checkout@v5
        with:
          ref: refs/pull/${{ github.event.pull_request.number }}/merge
      - 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

Volatile note: the recommended/default model and the CLI version rot. Leave model unset to track the default, or pin codex-version deliberately for reproducibility — and check https://developers.openai.com/codex/models and https://github.com/openai/codex/releases.

The safety-strategy input controls OS-level privilege reduction before Codex runs — a layer beneath the sandbox. Its job is to ensure that even if an agent run is compromised, it can't trivially exfiltrate OPENAI_API_KEY or wreck the machine.

The guidance is blunt: keep safety-strategy on drop-sudo (or move Codex to an unprivileged user) so a compromised run can't read your key out of the environment or escalate. Only drop to unsafe when the platform forces you to (Windows), and compensate by tightening everything else — sandbox, key scoping, who can trigger.

Notice the defense-in-depth stacking: safety-strategy (OS user/privilege) sits under the sandbox (where Codex may read/write/network), which sits under the approval policy (when it must ask — largely moot in unattended CI). In a pipeline you lean hardest on the bottom two layers, because the top one has no human to ask.

The headline automation: when CI fails, fire a second workflow that lets Codex edit the code with workspace-write and then open a PR with the fix. The trigger is workflow_run filtered to a failed conclusion:

on:
  workflow_run:
    workflows: ["CI"]
    types: [completed]

jobs:
  autofix:
    if: ${{ github.event.workflow_run.conclusion == 'failure' }}
    runs-on: ubuntu-latest
    env:
      OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
    steps:
      - uses: openai/codex-action@v1
        with:
          openai-api-key: ${{ secrets.OPENAI_API_KEY }}
          prompt: "You are working in a Node.js monorepo with Jest tests. Fix the failing CI."
          codex-args: '["--config","sandbox_mode=\"workspace-write\""]'
      - uses: peter-evans/create-pull-request@v6
        with:
          branch: codex/auto-fix-${{ github.event.workflow_run.run_id }}
          title: "Auto-fix failing CI via Codex"

The moving parts:

• Trigger on failure only — the if: guards on conclusion == 'failure' so it doesn't run on green builds.
• workspace-write is required because, unlike the review job, this one must edit files. (Remember: codex exec defaults to read-only; you must opt in to writing.)
• Open a PR, don't push to main. Routing the fix through a PR keeps a human review gate on AI-authored changes — exactly the oversight CI otherwise removes.
• Pin the action. The cookbook pins @main for the demo; in production pin @v1 or a SHA.

This pattern is powerful and risky in equal measure: an agent is now writing code on a trigger you don't watch. The mitigations from this whole lesson apply at once — scope the key, keep drop-sudo, write to a branch + PR (never main), and restrict who can cause the upstream workflow to run.