How to Review GitHub Pull Requests with Codex

Teams already running Codex still treat pull request review as a chat habit. The official GitHub path is a tighter loop: Codex reads the diff, applies repository guidance, posts a standard GitHub review, and can take a follow-up fix on the same branch.

This walkthrough follows that documented path. Enable Code Review, trigger @codex review, encode checks in AGENTS.md, optionally turn on Security Review, then ask Codex to fix what it found.

What you need first

Before Codex will review a pull request, confirm you have:

Codex cloud set up for the repository you want reviewed
Access to Codex code review settings
An AGENTS.md file if you want Codex to follow repository-specific review guidance

To configure automatic reviews, you also need a connected GitHub repository and GitHub push or admin permission for its settings.

Enable Code Review

Set up Codex cloud for the repo.
Open Codex settings.
Turn on Code review for that repository.

That toggle is the gate. Manual mentions and automatic reviews both depend on it.

Request a review

In a pull request comment, use the exact trigger:

@codex review

Wait for Codex to react with 👀 and post a review. It reviews the pull request diff, follows your repository guidance, and leaves a standard GitHub code review focused on serious issues—the same shape of review a teammate would leave.

On GitHub, Codex flags only P0 and P1 issues so comments stay on high-priority risks.

For a one-off focus, add it in the same comment. The docs show:

@codex review for issues in the database migration

The GitHub code-review use case also uses a broader starter prompt:

@codex review for security regressions, missing tests, and risky behavior changes.

Review every new pull request automatically

If you want Codex on every pull request without a mention, turn on Automatic reviews in Codex settings. Codex then posts a review whenever someone opens a new PR for review.

The use-case page frames this as another review signal before human merge approval, especially on large production codebases. It can surface regressions, missing tests, and documentation issues directly on the pull request.

Teach Codex what to flag

Codex searches the repository for AGENTS.md files and follows the applicable code review rules. Add a ## Code Review Rules section to the file closest to the code the rules govern. Use ### headings to group related checks when that helps.

The official example is an experiment-reporting service that must not let post-exposure behavior reshape a comparison cohort:

## Code Review Rules

### Experiment cohorts

- Do not filter treatment comparisons on post-exposure behavior, including conversion or retention.
 Safe path: build cohorts from assignment or exposure; report conversion as an outcome.

Put repository-wide rules in the root AGENTS.md. Put service-specific rules in a nested file, such as services/experiment_reporting/AGENTS.md. Codex applies the root file plus the more-specific guidance that covers each changed file, so unrelated changes do not pick up another service’s context.

Start with two or three concise rules that encode checks reviewers already explain out loud. The docs recommend:

Focus on consequential, repository-specific behavior—compatibility constraints, data boundaries, unsafe side effects—and why they matter.
State the safe path or exception so Codex can tell a real issue from expected behavior.
Keep rules scoped and durable. Prefer outcomes over function names that will change, and keep guidance near the code it governs.
Leave mechanical checks in CI. Formatting, lint, and other deterministic checks do not belong in review rules.

Then open a representative pull request and request @codex review. Refine the rules from the findings. Narrow or remove guidance that produces noise.

These rules guide Codex. They do not replace tests, branch protections, or required approvals. Both official GitHub integration pages use the same heading: ## Code Review Rules.

Optional: Security Review

Security Review is a separate research-preview pass for teams that want extra attention on security issues. It goes deeper than Code Review on security-specific risks by analyzing the pull request diff, supporting repository context, and configured threat models or security guidance. Code Review can still flag security-related issues, so you may see occasional overlap.

It is available to ChatGPT Enterprise, Business, Edu, and Pro customers. It is not available on Plus. During the introductory period it does not consume ChatGPT credits, though usage limits may apply. An existing Codex Security scan is optional.

To configure it:

Set up Codex cloud with a connected GitHub repository.
Open Codex settings.
Under Repository preferences, choose which pull requests get Security Review and when it runs.

You can select Whenever code review runs so it runs alongside Code Review. Other timing options are On PR open and Every push. Scope options include Follow personal, Review all PRs, and Review team PRs when available. “Team” here means members of your ChatGPT workspace, not a GitHub team.

You can attach a threat model for assets, trust boundaries, and repository-specific risks. If you do not specify a source, Codex regenerates the threat model for every review.

Reporting thresholds are separate from Code Review’s P0/P1 filter. By default, automatic Security Reviews report High and Critical findings; manually requested reviews report Medium, High, and Critical. You can change those minimums independently and add path-based overrides. Findings posted on a pull request inherit that PR’s GitHub visibility—including on public repos—so choose thresholds carefully. The threshold controls what Codex posts to GitHub; the full report stays in Codex.

To request it by hand, comment:

@codex security review

Codex reacts while the review runs, then posts findings that meet the manual reporting threshold. Open the associated Codex task and select the Security Report tab for the full report, including severity, attack path, supporting evidence, validation, and remediation guidance. If nothing meets the threshold, Codex does not post findings to the pull request.

Fix findings on the same PR

After Codex posts a review, leave another comment:

@codex fix the P1 issue

The use-case page also shows @codex fix it. Codex starts a cloud chat with the pull request as context and can push a fix back to the branch when it has permission.

Any @codex mention that is not review starts a cloud chat on that pull request. The docs also show:

@codex fix the CI failures

If Codex stays silent

If Codex does not react or post a review:

Confirm Code review is on for the repository in Codex settings.
Confirm the pull request belongs to a repository with Codex cloud set up.
Use the exact trigger @codex review in a pull request comment.
For automatic reviews, confirm Automatic reviews is on and that the pull request event matches your review trigger settings.

That is the loop the docs encode: enable the feature, trigger a review, put repo-specific checks in AGENTS.md, optionally deepen security, then hand the same PR back to Codex for a fix.

Next step: Open a representative pull request, comment @codex review, and write two or three ## Code Review Rules in the nearest AGENTS.md based on what it missed or over-flagged. If you need the security pass, read the Security Review setup options before you turn it on for every PR.