Codex Review Check

Codex Review Check is a read-only, credit-aware GitHub Action that guides agents through the Codex review loop: a completed review holds the quality floor by default, and require-lgtm: true raises the bar to a current-HEAD Codex LGTM.

Installation

1. Copy the ready-to-use examples/codex-review-check.yml into the consuming repository as .github/workflows/codex-review-check.yml. The example pins the Action to a reviewed full commit SHA and grants only read permissions.
2. Enable Codex code review for the repository with the On pull request trigger, so each pull request receives an initial review.

Usage

Open or update a pull request, then watch the normal check interface:

gh pr checks --watch

When gh pr checks reports a failure, the failure log line gives the agent one concrete next action and keeps review-credit decisions explicit:

$ gh run view --log-failed
...
##[error]No Codex review signal for current HEAD 821c759c9c3256e8a677800dbe8e4a88ae5e2ab0. Request one and run these back to back, without waiting in between: gh pr comment 42 --body '@codex review' && gh run rerun 33499862152 --failed && gh pr checks 42 --watch. The re-run check itself waits up to 30 min for the Codex review to finish, then passes or reports the next action. Start it right away and wait on the check; read Codex reviews or comments directly only if the check result looks wrong.

The job summary mirrors the same guidance in the web UI for human debugging.

The initial review only covers the first HEAD. When a later push needs another review, the failure prints the explicit request command — gh pr comment <PR> --body '@codex review' — for the agent to run; the Action never spends Codex credits itself. By default a completed review passes once its threads are resolved; set require-lgtm: true to require a current-HEAD LGTM.

The check follows this state model — the loop over time:

---
config:
  look: neo
  theme: redux
---
flowchart TB
    A([Run / rerun]) --> B{1 · threads}
    B -- unresolved --> C[Fail · fix, or reply with reasoning and resolve]
    C --> A
    B -- clear --> D{2 · new liveness}
    D -- "📝 Code Review on HEAD · 🔄 Running" --> E[Wait for the verdict]
    E --> A
    E -- "5 · review-timeout" --> J[Fail · review never finished]
    J --> A
    D -- none --> F{3 · verdict}
    F -- "4 · none past grace" --> G[Fail · @codex review hint]
    G --> A
    F -- "lenient · any HEAD" --> H([Pass])
    F -- "strict · LGTM" --> H
    F -- "strict · no LGTM" --> I[Fail · re-review hint · after grace + settle]
    I --> A
    classDef pass fill:#dafbe1,stroke:#1a7f37
    classDef fail fill:#ffebe9,stroke:#cf222e
    class H pass
    class C,G,I,J fail

Loading

And its evaluation order — each evaluation stops at the first match:

1 · unresolved Codex threads    → fail · fix, or reply with reasoning and resolve
2 · a newer review is running   → wait (📝 Code Review on HEAD · 🔄 Running, or a fresh @codex review)
3 · completed verdict           → pass (usually ✅ Completed)
      lenient (default):  latest verdict, any HEAD
      require-lgtm:       LGTM on the current HEAD — a verdict without an LGTM fails with a re-review hint after grace + settle
4 · nothing after grace-seconds → fail · @codex review hint
5 · review never finishes       → fail at review-timeout-seconds

Configuration

See configuration, outputs, and reruns.

License

Apache License 2.0