Git and GitHub Integration: Let Codex Act as a Reviewer in Your PRs

📚 Series Navigation: The previous article [25 Parallel Isolation with Worktrees] taught you how to use Git worktrees to create independent paths for Codex tasks so they run concurrently without conflicts. This article moves the workspace from your local terminal to your GitHub repository: showing how to let Codex look into your Pull Requests to review code, check against your custom rules, and push fixes back to your branch. The next article [27 Automation and CI/CD] brings this flow into CI pipelines to run unattended tasks.

Let's discuss a scenario that occurs almost daily in team collaboration. From opening a PR to merging it, a huge block of time is spent waiting for a reviewer to look at it—teams are small, reviewers are busy, and your PR hangs there, often for a full day.

And when they finally review it, humans typically spot superficial issues: "this variable name could be better" or "this line is missing a space." Critical issues—race conditions, missing auth middleware, or logging PII (Personally Identifiable Information)—are tiring and easy to miss.

Codex's GitHub integration targets this: by typing @codex review in a PR comment, it scans the diff like a tireless teammate, identifies high-priority issues matching your repository guidelines, and flags them in the PR. You do not have to leave GitHub, and it does not bypass your merge approvals—it handles the review, and you click merge, matching the safety line we have maintained since [Article 15].

By reading this article, you will get:

• How a single @codex review triggers a review in a PR, what it returns, and which levels of issues it targets (P0/P1, officially)
• How to enable "Automatic reviews"—initiating reviews on every new PR without manual @ mentions
• How to customize review rules using AGENTS.md Review guidelines: blocking log outputs, requiring auth middleware on routes, etc.
• Asking it to modify code and push it back to the branch via @codex fix, and the permissions boundaries behind it
• The local /review command: checking code in the terminal before pushing it to GitHub, without modifying your workspace
• A rule of thumb: what to delegate to AI, and which boundaries to guard yourself

⚠️ The GitHub-triggered reviews (@codex review, automatic reviews) covered here depend on Codex Cloud, requiring a paid plan and authorized repository access. The local /review command does not require Cloud. We will keep these two paths separate.

---

01 Two Different Paths: Codex on GitHub vs. Codex in Your Terminal

Before starting, let's distinguish these two paths: Codex reviewing your code works in two completely different places.

Analogy: A teacher who reviews your homework after submission vs. one who sits next to you as you work. One is "after you write and submit it"; the other is "while you are writing it." Both are handled by the same teacher, but the scenario, permissions, and initiation are different.

For Codex, these two paths are:

Path 1: GitHub-triggered (Cloud). You comment @codex review in a GitHub PR, and Codex launches a task in the Cloud, scans the PR diff, and posts comments directly in the PR. The entire flow runs in GitHub, while the task executes on OpenAI's cloud servers (as covered in Article 10 Cloud Tasks). Prerequisite: the repository must be connected to Codex Cloud with the Code review feature enabled.

Path 2: Local /review (CLI). You run /review in your local Codex terminal session. It launches a reviewer locally, reads your selected diff (uncommitted changes, branch differences, specific commits), and lists issues in your terminal. It is read-only—never touching files in your active workspace. It does not connect to GitHub or require Cloud; it runs entirely locally.

Dimension	GitHub-Triggered @codex review	Local /review
Trigger Location	GitHub PR comment section	Terminal Codex session
Execution	Codex Cloud (Cloud)	Your local machine
Target	The PR diff	Selected diff (uncommitted / branch / commit)
Output	Posted as comments in the PR	Listed in your terminal review panel
Prerequisite	Connected Cloud + Code review enabled	None, ready out-of-the-box
Modifies Code?	No (unless you comment @codex fix)	No, read-only

This article focuses on Path 1 (GitHub-triggered)—as it is the core of Git and GitHub integration. We cover local /review in Section 06 as a "self-check" step before opening PRs.

💡 Summary in one sentence: Codex reviews code via two paths—GitHub @codex review runs in the cloud to post comments on your PR (requires Cloud + toggle enabled), and terminal /review runs locally to list issues without modifying code (ready out-of-the-box).

---

02 Commenting @codex review: Let It Spot Issues in Your PR

The core usage is simple: comment @codex review in a PR, and press enter.

Why delegate this to Codex? Because reviewing a PR thoroughly is tiring and easily delayed—when reviewers are busy, your PR queues up; and when they get to it, attention drifts after checking a few files. This "important but exhausting" task is what we should delegate to a tireless teammate.

Analogy: An editor hired to spot critical errors before publishing. After reading your draft three times, you miss typos because your brain fills in "what you meant to say." Handing it to a editor who targets structural errors forces focus: they don't care how smooth your style is, they check if "this logic breaks" or "this data contradicts itself." Codex acts as this editor in your PR: it doesn't praise your code style, it spots places that will fail.

In practice, go to GitHub and type this in your PR comment box:

@codex review

Once posted, the flow proceeds as follows:

1. Codex adds a 👀 reaction to your comment—indicating "received, analyzing" (the system is programmed to react with 👀 before posting the review).
2. It launches a task in the cloud, reads the PR diff, and compares it against your repository guidelines (Section 04).
3. Once done, it posts a code review in the PR, listing issues line-by-line under the corresponding files.

Here is an official priority setting you must keep in mind to avoid thinking it "missed" things:

In GitHub, Codex only flags P0 and P1 issues to keep review comments focused on high-priority risks.

Simply put: it avoids cluttering your PR with minor remarks. P0 (critical) and P1 (important) are the priority levels it targets—leaving out minor suggestions like "this variable name could be better" or "this line has an extra space." This keeps comments actionable: when using other AI review tools, I disliked getting forty suggestions on a minor PR, burying actual bugs. Codex's focus on P0/P1 ensures every comment is worth inspecting.

A real-world example: last month, a colleague opened a PR modifying payment webhook logic. I focused on checking amount calculations, but @codex review flagged a P1 issue—the webhook lacked idempotent checks, meaning duplicate calls would double-credit user balances. I had completely missed that.

💡 Summary in one sentence: Comment @codex review in a PR, and it reacts with 👀, scans the diff, and posts comments; it only flags P0/P1 issues to avoid noise, keeping comments actionable.

---

03 Automatic Reviews: Initiating Reviews Automatically on Every New PR

Commenting @codex review is a manual step. You will eventually forget it—especially on PRs opened by other teammates. Codex provides a setting: Automatic reviews (Automatic reviews).

Analogy: Shifting from "going for checkups only when you think of it" to "company-scheduled annual checkups." Manual reviews rely on your memory—which is easy to neglect. Automatic reviews build it into your workflow: running checkups automatically when a PR is opened, without relying on your memory. Delegate memory tasks to systems.

How to enable it:

If you want Codex to review every PR automatically, enable Automatic reviews in your Codex settings. When a new PR is opened for review, Codex posts comments without requiring a @codex review comment.

The setup involves two steps (configured in your ChatGPT settings, not GitHub):

1. Go to your Codex settings page on chatgpt.com (URL: https://chatgpt.com/codex/settings/code-review; or navigate via chatgpt.com → Codex → Settings → Code review).
2. Toggle Automatic reviews to enabled.

Once enabled, Codex reviews new PRs automatically, saving you and your team from remembering to call it.

When should you use manual vs. automatic reviews? A common split:

• Team repositories with active collaboration → Enable automatic reviews. Let it act as a "first gate" reviewing every PR.
• Personal playground projects with minor changes → Use manual @codex review comments to avoid running it on every commit.
• Large changes requiring a specific focus → Even if automatic reviews are active, you can call it manually with a specific focus (e.g., @codex review for security regressions, detailed next) to re-evaluate the diff.

Dimension	Manual @codex review	Automatic Reviews
Initiation	Commenting @codex review manually	Automatically on new PR creation
Reliability	Relies on memory, easily forgotten	System-enforced, never missed
Suitable For	Personal projects, minor edits, quick checks	Team repositories requiring checks on every PR
Granular Control	Trigger as needed, with optional custom focuses	Complete coverage of all incoming PRs

💡 Summary in one sentence: Automatic reviews are enabled via Automatic reviews in settings, reviewing every new PR automatically without manual mentions; recommended for team repositories, while manual comments are suitable for minor personal projects.

---

04 Customizing Review Rules: Defining Guidelines in AGENTS.md

You might ask: what guidelines does it check against? By default, it uses standard software quality rules; but you can define project-specific instructions using AGENTS.md.

As covered in Article 11, AGENTS.md lists repository guidelines. Review rules go under a specific section—officially named Review guidelines.

Analogy: Handing a quality inspector a checklist of "our factory's specific priorities." Standard checks are common (checking if screws are tight, checking for scratches), but your line has specific requirements—such as "this batch is exported to the EU, so environmental labels must be verified." Writing these on a list posted on the wall ensures the inspector checks them. The Review guidelines section in AGENTS.md is that checklist.

Example written in the root AGENTS.md:

## Review guidelines

- Don't log PII.
- Verify that authentication middleware wraps every route.

With these written, Codex targets these checks specifically in every review.

Here is a convenient mechanism that matches the proximity rule covered in Article 11—the official docs state:

Codex applies the AGENTS.md instructions closest to the modified files. You can place specific instructions deeper in your directory structure to apply extra checks on critical modules.

This means you don't have to list all rules in the root file. For payment modules, write rules in src/payment/AGENTS.md; they apply automatically when changes touch payment code. This matches the "closest wins" rule of AGENTS.md, which is fully supported in reviews.

Example src/payment/AGENTS.md:

## Review guidelines

- Money calculations must use Decimal; float operations are forbidden.
- Webhooks must require an idempotency key to prevent duplicate credits.

When Codex reviews changes in the payment module, it checks these rules specifically—helping catch issues like the missing webhook idempotency check.

You can also specify a one-time focus: if you don't want to edit AGENTS.md but want to target a specific check on a PR, specify it in your comment:

@codex review for security regressions

This instructs it to focus on security regressions for this run. The docs list another example: if you want it to flag typos, write "Treat typos in docs as P1" in AGENTS.md—and it will flag them as P1 issues.

💡 Summary in one sentence: Custom rules go under the Review guidelines section in AGENTS.md; the proximity rule allows you to define stricter guidelines for critical paths like payment directories; and you can pass one-time instructions via @codex review for xxx in comments.

---

05 Applying Fixes Directly: @codex fix and Permissions Boundaries

Codex completed its review and flagged a P1 issue. What next? You can comment to ask it to fix the issue—and it will push the change directly to the PR branch.

Analogy: An editor who not only marks errors but edits the text directly. An editor typically marks a sentence, leaving you to rewrite it. Codex can go further—if you say "please fix this for me," it modifies the code and pushes the updated version back to your branch. But note: it can only do this if you grant it write permissions to the repository.

Comment in the PR:

@codex fix the P1 issue

The official docs describe the behavior:

Codex uses the PR as context to start a cloud task and, provided it has permissions, pushes the fix back to the branch.

This highlights two key aspects matching our safety boundaries:

First: @codex fix starts a cloud task. It does not edit code in the comment box; it launches a Codex Cloud task (Article 10), loads the PR files as context, runs its "think → act → observe" loop, and validates the change.

Second: "provided it has permissions" is key. Whether it can push to the branch depends on the write permissions you granted to Codex. As emphasized in [Article 15 Permissions] and [Article 16 Safety]: action boundaries are governed by permissions, not model capabilities. If you do not grant write permissions, it lists the fix in comments but cannot push it.

Do not confuse these two commands:

• @codex review → Launches the code review workflow (reviews only, does not modify code).
• @codex <anything else> (e.g., @codex fix the CI failures or @codex add tests for this route) → Launches a general cloud task using the PR as context to perform work.

The official docs clarify:

If you @codex followed by anything other than review, Codex uses the PR as context to launch a cloud task.

Thus, review is a reserved keyword for the review workflow, while other prompts launch general cloud tasks. Keep this in mind to understand why @codex fix modifies files instead of reviewing them.

A safety reminder matching our core rules: @codex fix pushes changes directly to your remote branch. This is convenient, but the decision to merge the changes into the main branch remains yours. Let it fix code and push to a branch, but never delegate the merge button (Merge PR) to AI—matching the rule from [Article 25] that "AI drives in its lane, but you approve the merge."

💡 Summary in one sentence: Comment @codex fix the P1 issue to launch a cloud task that modifies code and pushes the fix back to the branch (provided it has write permissions); note @codex review is reserved for reviews, while other prompts run general tasks; and always handle the final merge manually.

The GitHub review flow:

Diagram: A PR creation or update triggers a review via @codex review comments or automatic reviews; Codex loads the PR diff in the cloud, checks it against the closest AGENTS.md review guidelines, posts comments for P0/P1 issues, and updates the branch on @codex fix calls.

---

06 Local /review: Checking Code Before Opening PRs

The previous sections focused on GitHub. But a common scenario occurs earlier: checking your changes locally before pushing code and opening a PR—using /review without connecting to GitHub.

Analogy: Checking your answers before submitting your exam paper, rather than waiting for the teacher to mark them wrong. Instead of pushing common errors and getting comments on your PR, run a self-check locally to clean up obvious issues first. This reduces back-and-forth loops.

Run this command in your local Codex session:

/review

The system prompts you with several review presets, launching a local reviewer to scan your diff and list prioritized, actionable issues without modifying your files (read-only). The presets include:

• Review against a base branch (Review against a base branch): compare against a local branch, diffing your changes to spot major risks before opening a PR.
• Review uncommitted changes (Review uncommitted changes): scans staged, unstaged, and untracked changes in your workspace.
• Review a commit (Review a commit): scans changes in a specific commit selected by SHA.
• Custom review instructions (Custom review instructions): pass a custom instruction (e.g., "focus on accessibility regressions") to the reviewer.

An official configuration tip: /review uses your session's active model by default; to use a stronger model for reviews, set review_model in config.toml. Running daily sessions on a fast model and assigning a stronger model to review_model is a practical trade-off.

I use local /review as a pre-flight check:

1. After coding, run /review in the terminal and select Review uncommitted changes.
2. Fix the flagged issues locally.
3. Commit, push, and open the PR once the local check is clean—ensuring the remote @codex review (or automatic reviews) flags only high-level details.

Checking code locally keeps your remote PR history clean. This reduces review loops significantly.

💡 Summary in one sentence: Local /review acts as a pre-flight self-check in your terminal (offering presets for uncommitted changes, branch diffs, specific commits, or custom prompts) that runs in a read-only mode to list issues; fix them locally before pushing to keep remote reviews clean; use review_model to set a dedicated model for reviews.

---

07 Installing gh: Helping Codex Desktop Load PR Details

If you work in the Codex Desktop App (Article 07) or IDE extensions (Article 09), we recommend installing GitHub's official CLI tool gh.

Analogy: Handing your assistant a security badge to enter the records archive. Without it, he knows "a PR exists," but cannot load its comments, history, and discussions (PR context, reviewer comments). Logging in with gh lets him access the complete file history.

The official docs state:

Install the GitHub CLI (gh) and authenticate using gh auth login to allow Codex to load PR context, review comments, and modified files. If gh is not installed or authenticated, PR details may not display in the sidebar or review panel.

Simply put: installing and authenticating gh allows the Codex Desktop sidebar to load PR contexts, reviewer comments, and changed files, letting you address comments in the same window. Without it, these details are omitted.

Installation and login steps (by platform):

# macOS (Homebrew)
brew install gh

# Windows (winget)
winget install --id GitHub.cli

# Log in on any platform after installation
gh auth login

ℹ️ Linux installation steps vary by distribution (apt / dnf / pacman etc.); refer to the official GitHub CLI installation guide. Run gh auth login after installation.

Once authenticated, the workflow for addressing PR comments in a single interface:

1. Open the review panel on the PR branch.
2. Inspect the PR context, comments, and changed files.
3. Instruct Codex to address specific comments.
4. Review the generated diff in the panel.
5. Stage, commit, and push back to the PR branch when ready.

Note step 5: "push back when ready." The decision to push changes back to the remote branch remains under your control.

A security reminder matching Article 16 on prompt injection: PR comments, reviewer feedback, and linked issues are "external content" that can theoretically contain hidden instructions for the AI. Let it read and address comments, but do not let it execute commands or visit URLs blindly—inspect comments containing unusual instructions manually.

💡 Summary in one sentence: Install and authenticate gh using gh auth login when working in the Desktop App or IDEs—allowing Codex to load PR contexts, comments, and files; the push action remains under your control; and check comments for prompt injection.

---

08 Guarding the Line: Merge and Force-Push Actions Remain Manual

Having covered what to delegate, let's look at the boundary you must guard yourself—extending from Article 15 and 16, and critical in Git workflows.

Analogy: An assistant edits a contract, but only the authorized signer executes it. The assistant manages revisions, formatting, and terms; but executing the contract commits the company and cannot be undone—requiring an authorized human signature. In Git, that signature is merging into main and force-pushing to remote history.

Why these two? The table explains:

Operation	Can you undo it?	Executed by
@codex review / Local /review	— (Read-only, no file changes)	✅ Delegate
@codex fix pushing to a PR branch	Yes (branches can be updated or deleted)	✅ Delegate with review
Merging a PR into main	Affects the team; hard to undo	⚠️ Human click
git push --force modifying history	No, risks overwriting teammate commits	❌ Human only

Two rules I follow strictly:

First: always handle merges manually. Codex can review, fix, and push changes to a branch—actions that are reversible (deleting a branch if unsatisfied). But merging changes into main affects the stable branch all developers build upon. This step must be human-executed: you decide if the PR is ready to merge.

Second: never delegate force-pushes to AI. git push --force overwrites remote history and can erase other developers' commits. This action must always be run manually, double-checking the target branch before running. I have seen automated scripts force-pushing to master and wiping out a morning's worth of team commits. Do not create paths for AI to run force-pushes.

Recall from Article 15: Codex's codex exec command defaults to a read-only sandbox—not because of capability limits, but to keep active scopes minimal by default, requiring explicit --sandbox workspace-write switches to write changes. This "minimal by default, explicit to expand" design logic matches manual merges and force-pushes: the less reversible an action is, the more it requires human execution.

💡 Summary in one sentence: Delegate reviews, fixes, and branch updates; but handle PR merges manually and run force-push commands yourself—reversible actions can be automated, while irreversible ones require explicit human confirmation, matching Codex's read-only sandbox design philosophy.

---

09 The Teamwork Model: Codex Reviews, You Merge

Combining these steps gives a clear mental model—Codex acts as the reviewer and editor in the Git workflow, while you hold merge approvals.

Diagram: The PR lifecycle spans local /review self-checks (green, read-only) to remote @codex review calls in the cloud (for P0/P1 issues, with optional fixes), ending at the human merge decision (red, irreversible).

This model prevents two extremes: you don't have to review every line manually (losing AI efficiency gains), nor do you delegate merges and force-pushes (risking master branch errors). The AI handles reviews and edits, and you manage approvals.

---

10 Hands-on: Running a Local /review Self-Check

GitHub-triggered reviews depend on cloud setups and repository access; however, local /review runs out-of-the-box, allowing you to test code checks locally. This flow runs entirely on your machine in a read-only mode.

Step 1: Set up a temporary Git repository (run in your terminal, not in Codex)

mkdir review-demo && cd review-demo
git init
printf 'def get_user(uid):\n    return db.query("SELECT * FROM users WHERE id=" + uid)\n' > app.py
git add app.py && git commit -m "feat: initial get_user"

Expected: git init initializes the repository, and the commit prints [main (root-commit) xxxxxxx] feat: initial get_user followed by modification details. Note we intentionally wrote a SQL injection vulnerability (string concatenation in SQL query) in app.py—we want to verify if Codex flags it.

Step 2: Make a new modification (leave it uncommitted)

printf 'def get_user(uid):\n    return db.query("SELECT * FROM users WHERE id=" + uid)\n\ndef delete_user(uid):\n    db.execute("DELETE FROM users WHERE id=" + uid)\n' > app.py

Expected: No errors. The workspace now contains changes introducing a delete_user function, unstaged and uncommitted, which we want to check using the uncommitted changes preset.

Step 3: Enter the Codex session and run /review

codex

In the session, run:

/review

Expected: The review preset menu pops up. Use arrow keys to select Review uncommitted changes and press enter.

Step 4: Inspect the output

Expected: Codex launches the reviewer, scans the uncommitted diff, and lists prioritized issues in the terminal review panel. It should identify the SQL injection in delete_user (concatenating uid into the query), flagging it as a high-priority issue and suggesting parameterized queries. Verifying this confirms it scans the changes accurately. Note app.py remains unmodified—confirming the read-only nature of /review.

ℹ️ The exact issues list, phrasing, and whether it flags the older query depend on the model run; the goal is verifying it spots the SQL injection risk without modifying files.

Step 5: Cleanup (Optional)

cd .. && rm -rf review-demo

Running these steps verifies the workflow: using /review to check uncommitted code locally. Once your repositories connect to Codex Cloud, combine this local self-check with remote reviews.

💡 Summary in one sentence: The hands-on workflow has five steps—create a temporary Git repository with a SQL injection → make uncommitted changes → run /review selecting uncommitted changes → check that it flags the injection without modifying files → clean up; verifying local self-checks on your machine.

---

11 Summary

We have explored integrating Codex with Git and GitHub—shifting from tool capabilities to managing review workflows, automatic reviews, guidelines, fixes, and safety boundaries.

Let's review the key points:

Task	Execution	Key Takeaway
Review a PR	Comment @codex review in PR	Runs in cloud, flags P0/P1 issues, posts comments on files
Review automatically	Enable Automatic reviews in settings	System-enforced checkups, recommended for team repositories
Custom review guidelines	Write Review guidelines in AGENTS.md	Proximity rule allows specific rules for subfolders (e.g., payment modules)
Apply fixes	Comment @codex fix the P1 issue	Runs a cloud task and pushes changes (requires write permissions)
Pre-flight self-check	Run /review in terminal	Read-only local check, fix issues locally before pushing
Load PR details in App	Install gh + run gh auth login	Authenticates access to PR comments and files in the desktop UI
Guard safety lines	Merges and force-pushes remain human actions	Irreversible operations require explicit human actions, matching read-only defaults

You should now be able to: distinguish between cloud @codex review and local /review paths; manage remote reviews using comments, automatic settings, Review guidelines in AGENTS.md (applying proximity rules), and @codex fix tasks; run local /review checks on uncommitted code; and authenticate gh to load contexts while keeping merges and force-pushes manual. You can now delegate code reviews to Codex to save team time while maintaining control over the stable branch.

---

The next article [27 Automation and CI/CD]—this article covered manual or semi-automated reviews triggered by PR events. The next article covers complete automation: using codex exec in GitHub Actions pipelines to let Codex launch automatically when CI builds fail, write fixes, and open PRs unattended. This shifts workflow capabilities to autonomous tasks running while you sleep.

---

Recommended Reading

• Agent Skills: Packaging Workflows to Teach Codex New Capabilities
• Comprehensive Guide: Adding Features and Committing a dummy TODO Tool
• IDE Extensions (VS Code etc.)