GitHub Integration

Your team opens a pull request, a reviewer is busy for two days, and the PR sits idle. Meanwhile, another teammate mentions a bug in an issue and nobody has bandwidth to investigate. What if an agent could review every PR within minutes of opening and start working on issue comments the moment they are posted? That is exactly what Codex does when connected to GitHub.

What You’ll Walk Away With

• Codex Cloud connected to a GitHub repository
• @codex review working on pull requests for on-demand code reviews
• Automatic code reviews enabled for every new PR
• @codex mentions in issues and PR comments triggering cloud tasks
• Review guidelines in AGENTS.md customizing what Codex flags
• A working workflow from issue to PR to merge

Prerequisites

GitHub integration requires:

• ChatGPT subscription (Plus, Pro, Business, or Enterprise) — API key auth does not support cloud features
• Codex Cloud environment configured with your repository
• Repository admin access (or someone with admin access to approve the Codex GitHub app)

Connect a Repository to Codex Cloud

1. Open chatgpt.com/codex in your browser.

2. Go to Settings > Environments and click New Environment.

3. Connect your GitHub account if you have not already. This installs the Codex GitHub app on your account or organization.

4. Select the repository you want Codex to work with.

5. Configure the environment: choose the branch, set up any required environment variables, and define setup commands (like npm install or pip install -r requirements.txt).

6. Save the environment. Codex can now launch cloud tasks against this repository.

Note

You can connect multiple repositories, each with its own environment configuration. Codex Cloud spins up a separate environment for each task.

On-Demand Code Reviews

Once your repository is connected, any collaborator can request a Codex review by commenting on a pull request.

Request a Review

Add a comment on any PR:

@codex review

Codex reacts with an eyes emoji to acknowledge the request, reads the PR diff, and posts a standard GitHub code review with inline comments — just like a human reviewer.

Focus a Review

You can scope the review to specific concerns:

@codex review for security regressions

@codex review focusing on error handling and edge cases

@codex review the database migration for data loss risks

Tip

Prompt to test your first code review:

Open any existing PR in your connected repository and comment:

@codex review

Within a few minutes, Codex should post a review. If nothing happens, verify that the repository has Codex Cloud enabled and that code review is turned on in settings.

Enable Automatic Reviews

If you want Codex to review every PR without being asked:

1. Go to chatgpt.com/codex/settings/code-review.

2. Toggle on Automatic reviews for your repository.

3. Save. From now on, Codex posts a review whenever a new PR is opened for review.

Automatic reviews use the same review guidelines from your AGENTS.md files. Codex flags only P0 and P1 issues by default — it does not nitpick formatting or style unless your AGENTS.md tells it to.

Customize Review Guidelines

Codex applies guidance from the closest AGENTS.md to each changed file. Add a “Review guidelines” section to your project’s AGENTS.md:

## Review guidelines

- Flag any API endpoint missing authentication middleware.
- Flag any database query using string interpolation instead of parameterized inputs.
- Verify that new dependencies have an active maintainer and more than 1000 weekly npm downloads.
- Treat typos in user-facing strings as P1 issues.
- Do not flag formatting issues -- ESLint handles those.

For package-specific scrutiny, place a more targeted AGENTS.md deeper in the tree:

packages/payments/AGENTS.md

## Review guidelines

- Every change to payment logic must include a test case.
- Flag any modification to the refund flow that does not update the audit log.
- Verify PCI compliance: no card numbers logged, no plaintext storage.

Trigger Cloud Tasks from GitHub

@codex review is one specific command. Any other @codex mention in a PR or issue comment triggers a general cloud task using the PR or issue as context.

Fix CI Failures

When CI is red on a PR, comment:

@codex fix the CI failures

Codex launches a cloud task, reads the CI logs, identifies the failing tests, and pushes a fix commit to the PR branch.

Implement from an Issue

On an issue describing a bug or feature request, comment:

@codex implement this

Codex creates a new branch, implements the changes based on the issue description, and opens a PR.

Follow Up on Review Comments

After reviewing a PR, a human reviewer might add feedback. Codex can address it:

@codex address the review feedback

Tip

Prompt to delegate a real task from GitHub:

Open an issue in your connected repository and comment:

@codex investigate this issue, identify the root cause, and suggest a fix in a new PR

Watch the Codex Cloud dashboard at chatgpt.com/codex to monitor progress in real time.

The Full PR Workflow

Here is how an end-to-end workflow looks with Codex and GitHub:

1. A developer opens an issue describing a bug.

2. The developer (or a bot) comments @codex implement a fix for this issue.

3. Codex Cloud launches a task, reads the issue, clones the repo, identifies the root cause, implements a fix, and opens a PR.

4. Codex automatically reviews the PR (if automatic reviews are enabled) or a teammate comments @codex review.

5. The human reviewer reads Codex’s review, adds their own feedback.

6. If changes are needed, comment @codex address the review feedback on the PR.

7. Codex pushes follow-up commits.

8. The reviewer approves and merges.

Local Surfaces and Git

The App, CLI, and IDE extension also integrate with Git, but they work with your local repository rather than through GitHub’s API.

App

The Codex App has built-in Git tools: view diffs, stage/unstage files and hunks, commit, push, and create PRs directly from the review pane. Worktree threads automatically create isolated branches.

CLI

The CLI runs git commands in your project directory. Ask Codex to commit, push, or create branches. Use /review in the TUI for local code review before pushing.

IDE Extension

The IDE extension can delegate to Cloud for PR-based workflows, or work locally with your Git state. It shares worktree context with the App when both are open.

When This Breaks

@codex does not respond to comments: Verify the Codex GitHub app is installed on the repository’s organization/account. Check that the repository has a Codex Cloud environment configured. The Codex app needs access to read and write comments.

Review does not flag expected issues: Codex only flags P0 and P1 issues by default. Add explicit review guidelines to your AGENTS.md. For example, add “Treat typos in docs as P1” if you want Codex to catch typos.

Cloud task fails to create a PR: Check the environment configuration at chatgpt.com/codex. Ensure setup commands run successfully (Codex needs to build the project). Check that the branch permissions on GitHub allow the Codex app to push.

“MFA required” error: Codex Cloud requires multi-factor authentication. Enable MFA on your ChatGPT account (or social login provider).

Codex creates a PR but CI fails: Codex does not always run your full CI pipeline before opening a PR. Add "Always run the test suite before opening a PR" to your AGENTS.md review guidelines so Codex includes this step.

Tip

Prompt to verify your GitHub integration end-to-end:

Create a test issue in your connected repository:

Title: Test: Codex GitHub integration
Body: @codex tell me about this repository's structure

If Codex responds with a comment about your repo structure, the integration is fully working.

What’s Next

Run Your First Task Execute a real Codex task across all four surfaces and see results