Codex Code Review: Turn Findings Into a Merge Gate

How should you use Codex code review?

Use Codex code review as a focused source of candidate findings, not as the whole merge gate. Trigger a separate review, teach Codex durable repository invariants inAGENTS.md, verify consequential findings against code and tests, and require a repository-owned verdict for the exact pull request head before merge.

Codex's GitHub integration reviews the pull request diff, follows applicable repository guidance, and posts a standard GitHub review. OpenAI's currentCodex GitHub documentationsays the reviewer limits GitHub findings to P0 and P1 issues. That focus reduces comment noise, but it does not answer every merge question. Tests, branch policy, required approvals, and the maintainer's product judgment remain separate evidence.

How does Codex code review work?

Codex supports review at two useful points. Local /review in Codex CLI, the IDE extension, or the app inspects a selected diff and reports prioritized findings without changing the working tree. GitHub code review runs through Codex cloud, receives the pull request as its subject, and publishes findings where the team already discusses the change.

These surfaces complement each other. A local pass shortens the author's feedback loop. A GitHub pass creates separate, visible review evidence. A gate turns admitted evidence into a stable decision contract. If you need the broader CI architecture, start with themerge-safe AI code review workflow for GitHub.

If you need machine-readable Codex output, run a separate CI job withcodex exec and a JSON Schema, following OpenAI'sstructured code review example. Do not infer merge status by parsing @codex review prose, reactions, or comment absence.

Set up Codex code review on GitHub

Start by setting up Codex cloud for the repository. Then open Codex code review settings and enable the repository. On a pull request, add the exact comment @codex review. Codex reacts with an eyes emoji while it works and posts the review when it finishes.

1. Connect the repository to Codex cloud.
2. Open Codex settings and enable Code review for that repository.
3. Add two or three scoped review rules to the applicable AGENTS.md.
4. Open a representative pull request and comment @codex review.
5. Check whether the findings are consequential, evidenced, and correctly scoped.
6. Enable automatic reviews only after the representative test is quiet and useful.

Automatic review removes the manual trigger for new pull requests. It should not remove the current-head requirement. A push changes the reviewed subject, so the merge gate must confirm that its usable result describes the revision GitHub is currently evaluating.

For one-off emphasis, put the focus in the request, such as@codex review for security regressions. Keep durable invariants in the repository. Pull request comments remain attached to that pull request and do not govern future changes; repository rules remain versioned beside the code they govern.

Write Codex code review rules that reduce noise

Good review rules encode consequential judgment that a formatter, type checker, or unit test cannot settle. Put repository-wide rules in the rootAGENTS.md. Put service-specific rules in the nearest nested file so a database invariant does not compete for attention during an unrelated UI change.

OpenAI's July 2026custom code review rules reportdescribes an internal evaluation in which rule-guided variants recovered 98% of required custom findings, compared with 58.3% for the baseline. Treat those as vendor-reported results from that evaluation, not a prediction for your repository. The transferable lesson is the test design: include a known violation, a safe counterexample, and an unrelated change.

Each rule should contain four parts:

1. Invariant: the behavior that must remain true.
2. Consequence: the user, client, or security failure if it changes.
3. Safe path: the compatible implementation or explicit exception.
4. Scope: the files or subsystem to which the rule applies.

## Code Review Rules

### Public event compatibility

- Preserve existing `reviewgate-agent-result` fields for the current schema version.
  Removing or renaming a field breaks external repair loops. Add a versioned field or
  schema before changing the contract.

Do not copy CI into prose. “Run the formatter” is weaker than a formatter check. “Do not rename this public field without a versioned migration” captures history and consequence that the compiler may not know. Review the rules like code: test them, narrow noisy wording, remove obsolete constraints, and keep exceptions visible.

Separate comments, findings, and the merge verdict

The missing layer in most Codex code review guidance is an output contract. A GitHub comment is presentation. A finding is a checked claim. A verdict is a policy result for one revision. Treating those as three artifacts prevents a persuasive sentence from silently becoming merge authority.

ReviewGate makes that separation inspectable. Model output is parsed into structured candidates; deterministic code admits a blocker only when the model-supplied classification, severity, and confidence satisfy fixed predicates and repository evidence passes grounding checks. Completed reviews derive a score from1-5; inconclusive reviews return review_error with a null score. The GitHub publisher maintains one canonical summary. See thereview lifecycle and scoring contract for the complete public behavior.

ReviewGate does not ingest @codex review comments or convert them directly into a check. It runs a separate review through OpenRouter and emits its own current-head result. The contract below is an adapter pattern for teams using Codex, not a claim that the two products share review state.

{
  "schema_version": "reviewgate-agent-result/v1",
  "status": "passed",
  "score": 5,
  "reviewed_sha": "<current-pr-head>",
  "findings": []
}

Before merge, compare reviewed_sha with the current pull request head. Treat status == "passed" && score == 5 as a usable clean gate result. Open blockers satisfy.disposition == "still_open" && .blocking_reason != null. Areview_error result has a null score and must be retried or investigated. The complete field contract is documented inReviewGate's versioned artifacts guide.

The resulting decision matrix is deliberately small. It distinguishes stale review state from a real defect and makes the next action explicit instead of asking an agent to infer policy from comment prose.

The separation gives Codex a precise role: finding consequential defects and checking local invariants. Deterministic software handles identity, validation, repetition, and status. Maintainers retain intent and risk acceptance.

Already use @codex review? AddReviewGate as the current-head check and make the merge contract inspectable.

Turn Codex findings into a merge gate

Use the six-step workflow below when a Codex review must contribute to an enforceable decision. Every step emits evidence that the next step can inspect.

1. Define review scope. Describe the pull request intent, changed contracts, expected tests, and repository invariants before asking Codex to review the diff.
2. Request a separate review. Run @codex review on the pull request or enable automatic reviews, using scoped AGENTS.md rules for judgment that deterministic CI cannot express.
3. Verify each consequential finding. Tie every potential blocker to a changed location, repository evidence, a causal failure path, and an observable contract or test.
4. Apply deterministic policy. Let repository-owned code decide finding admission, severity, score, and check conclusion instead of parsing the tone of a review comment.
5. Bind the verdict to the current head. After every relevant push, require a fresh result for the exact revision GitHub is evaluating and retain unresolved obligations across reruns.
6. Leave merge authority explicit. Combine the current review result with tests, branch protection, approvals, and maintainer judgment before merging.

1. Define the reviewed subject

Name the pull request goal, base branch, current head, affected contracts, and tests that should settle deterministic behavior. A reviewer cannot infer an unstated product requirement, and a clean review of the wrong diff is not useful evidence.

2. Keep authorship and review contexts separate

Run the PR review separately from the authoring conversation. The model name alone does not create independence. The useful separation is a fresh invocation with a defined diff, review-only instructions, and no authority to rewrite its own policy. The same principle applies whenreviewing Claude-authored pull requests or when you need acurrent-head Cursor code review workflow.

3. Verify the causal claim

For every proposed blocker, ask: which changed line creates which observable failure, under which input or contract, and what evidence confirms it? A file path is not enough. A severity label is not enough. The claim should survive source inspection, a focused test, or a reproducible counterexample.

4. Apply policy outside the reviewer

Decide admissible severity, confidence, evidence, and error behavior in code. A missing reviewer result must become an explicit review error, not a silent pass. Keep the review job's operational state separate from the verdict: a workflow can complete while the review correctly reports that changes are needed.

5. Preserve obligations across new commits

A repair commit should not erase a finding merely because the next model response omits it. Carry the stable obligation forward until new evidence shows it is fixed, rejected, or accepted by policy. ReviewGate'sexact-head agent workflow binds result retrieval and disposition to repository, pull request, and reviewed SHA.

6. Make the merge decision visible

Require the current verdict, deterministic CI, branch protection, and any human approvals your risk model needs. A Codex review with no P0 or P1 comment means only that this review did not publish one. It does not prove the tests ran, the product intent is correct, or the latest revision is safe to merge.

Trace one Codex finding from comment to verdict

Suppose a pull request renames a public JSON field used by external agents. The code compiles and unit tests pass because the repository's own consumers were updated at the same time. A scoped AGENTS.md rule tells Codex to protect versioned artifact fields unless the change includes a compatible schema path.

Codex posts a P1 comment on the renamed field and explains that existing consumers will stop finding it. That comment becomes useful evidence only after the gate verifies the public schema, identifies the current field in the base revision, and confirms that the pull request provides neither an alias nor a new schema version.

The proof packet now has concrete parts:

• Subject: the exact head SHA containing the rename.
• Contract: the committed public JSON schema and compatibility rule.
• Evidence: the changed field plus the missing migration path.
• Failure path: existing clients deserialize the old field and lose it.
• Disposition: open until compatibility is restored or a versioned break is accepted.

If the author comments @codex fix the P1 issue, Codex can prepare a repair when repository permissions allow. The repair produces a new head. Rerun deterministic tests and review the new diff; then let the gate close the same stable obligation only when the compatible field or migration is present. The old verdict cannot authorize the new commit.

ReviewGate makes unchanged-head rereviews idempotent, retains an open finding when a later reviewer merely omits it, and requires higher confidence plus novelty evidence for blockers introduced after the first review. Repair authority remains outside the reviewer: the coding agent edits and tests; the gate re-evaluates evidence.

What does it mean when Codex leaves no comments?

No Codex comment means the completed review did not publish a P0 or P1 finding. It does not establish that every relevant contract was inspected, that deterministic tests passed, or that the result belongs to the latest commit. First confirm that Codex reacted to the exact trigger and posted a completed review rather than timing out or lacking repository access.

Then check the review subject. If the pull request changed after the review, request another pass and require the repository gate to name the new head SHA. Finally, inspect required CI and unresolved human comments. Silence becomes useful only when it is one explicit input in a complete decision record; it should never be converted into a synthetic “safe” finding or an automatic approval.

Avoid five common Codex code review failure modes

1. Turning every convention into an AGENTS.md rule. Broad rules compete for attention and create noise. Start with two or three consequential, non-obvious invariants.
2. Giving the reviewer mechanical work. Formatting, lint, type checks, and deterministic tests belong in CI. Reserve review attention for judgment and causal reasoning.
3. Letting a comment become policy by string matching. Parse a structured result or verify the claim independently. Prose wording changes; the repository contract should not.
4. Trusting a result for the wrong revision. Any relevant push makes an earlier verdict stale. Require an exact-head result before merge.
5. Making “no comment” mean “safe.” A timeout, permission error, or unavailable reviewer is not a clean review. Represent operational failure as an explicit error that cannot satisfy the gate.

Codex code review pre-merge checklist

• Codex reviewed the intended pull request diff in a separate review context.
• Applicable AGENTS.md rules are scoped, durable, and tested.
• Deterministic formatting, lint, test, and security checks ran outside Codex.
• Every blocking finding identifies repository evidence and a causal failure path.
• Unsupported, duplicate, and stale findings have explicit dispositions.
• The verdict names the repository, pull request, and current reviewed SHA.
• Reviewer failure becomes an error, never an implicit clean result.
• Required checks and human approvals apply to the revision GitHub will merge.
• A maintainer confirms that the change matches product intent and accepted risk.

ReviewGate packages this contract as an open-source GitHub Action. It has no ReviewGate subscription, but live model calls are billed through your OpenRouter key. It runs in your CI environment, publishes one living summary and a machine-readable fix list, and gives coding agents an exact-head repair loop. You can install the review gate from the workflow example or inspect thecomplete source and schemasbefore trusting it.

Questions about Codex code review