Connect Codex to GitHub

Codex’s GitHub integration links a repository to a Codex cloud environment so collaborators can comment @codex review or @codex security review on a pull request, turn on automatic reviews for every new pull request, or mention @codex with an instruction to start a cloud task. AGENTS.md supplies the review rules, and CI still decides what merges.

This page is for developers and tech leads who already run Codex locally and want it working on the team’s pull requests. The situation it fixes: pull requests wait two days for a first review, a flaky test turns CI red on a Friday afternoon, and the issue backlog grows faster than anyone can triage it. Connecting Codex to GitHub moves the first review and the first fix attempt onto an agent, while a required CI check and a named human keep the final say.

What you’ll have after connecting Codex to GitHub

• A cloud environment that installs your dependencies and runs your test suite, smoke-tested from the terminal before anyone relies on it
• @codex review and @codex security review working on pull requests, plus automatic reviews if you want them
• Review rules in AGENTS.md that turn “what should Codex flag?” into a versioned, reviewable file
• Two copy-paste comments that start cloud tasks from a red pull request and from an issue
• A merge gate that checks Codex’s work with tests and required checks instead of a human reading every line

What you need before you connect Codex to GitHub

• A ChatGPT plan that includes Codex: Plus, Pro, Business, Edu, or Enterprise. Cloud features need a ChatGPT sign-in; an API key does not give access to Codex cloud. See Codex authentication.
• Permission to install a GitHub app on the account or organization that owns the repository. In an organization, that usually means an owner approves the request.
• A test command that passes on a clean checkout. Codex’s review and its fixes are only as trustworthy as the checks it can run. If npm test needs a local database you started by hand, write that down before you start.
• An AGENTS.md at the repository root. If you do not have one yet, create it first with the AGENTS.md setup guide.

Connect a repository and create a cloud environment

The GitHub integration runs on Codex cloud: every review and every @codex task runs in a container built from an environment you define. Set that up first.

1. Open Codex on the web at chatgpt.com/codex and sign in with the ChatGPT account that holds your plan.

2. Connect GitHub when Codex asks for it. GitHub shows an installation screen for the app; grant it access to only the repositories you want Codex to work on rather than all repositories in the organization.

3. Create an environment for the repository. Pick the default branch, then add setup commands that install dependencies exactly as CI does, for example npm ci or pip install -r requirements.txt.

4. Add the environment variables the test suite needs. Give it test credentials only. Anything in the environment is readable by the agent and by any task someone starts with a comment.

5. Save the environment and note its ID. The terminal commands in the next section use it.

Menu labels in Codex on the web change between releases; the flow above matches OpenAI’s GitHub and cloud-environment guides as read on 2026-08-28. Container caching, internet access and best-of-N attempts are covered in Codex cloud environments.

Smoke-test the environment from the terminal

A misconfigured environment is a common reason @codex tasks fail, and the failure shows up later as a vague comment on a pull request. Check it once from the CLI before you tell the team. codex cloud is marked [EXPERIMENTAL] in Codex CLI 0.157.1, and all the subcommands below come from that version’s --help.

codex cloud list --env ENV_ID          # the environment is reachable and lists its tasks
codex cloud exec --env ENV_ID --branch main "Run the full test suite and report the exact command, the pass and fail counts, and any setup step that failed. Do not change any files."
codex cloud status TASK_ID             # poll until the task finishes
codex cloud diff TASK_ID               # should be empty: the prompt forbade changes

ENV_ID is the environment ID from step 5; TASK_ID is printed by codex cloud exec. --branch defaults to your current local branch; pin it to the branch CI last ran green on so the counts are comparable. If the test count Codex reports differs from what CI reports on the same commit, fix the setup commands now. A review agent that cannot run your tests is guessing.

Copy-paste prompt: environment smoke test

Run the full test suite for this repository exactly as CI does. Report: the command you ran, the number of tests passed, failed and skipped, the total runtime, and every setup or install step that printed an error or warning. Do not modify any files and do not open a pull request.

Turn on Codex code review for the repository

Code review is a per-repository setting in Codex on the web. Open Codex’s settings, find code review, and enable it for the repository you connected. The same place offers automatic reviews, which make Codex review each new pull request without anyone asking (OpenAI’s GitHub guide, read 2026-08-28; labels may differ).

Which one to start with depends on your team:

Situation	Start with	Why
First two weeks, rules still unwritten	On-demand @codex review	You see what Codex flags on real pull requests before it comments on every one
Rules in AGENTS.md have been tuned on 10 or more pull requests	Automatic reviews	Every pull request gets a first pass, including the ones nobody remembered to ask for
Public repository with outside contributors	On-demand only	Keeps agent time and attention on pull requests a maintainer has already looked at

Request a review with @codex review

On any pull request in the connected repository, post a comment:

@codex review

Codex reviews the pull request’s changes and posts its findings back on the pull request. For a security-focused pass, use the second command OpenAI documents:

@codex security review

OpenAI also lists GitLab as a review surface: @codex review works on merge requests, and GitLab support is in beta on all ChatGPT plans (OpenAI’s GitLab guide, checked 2026-10-12). The setup differs, so this page covers GitHub only.

Keep the security pass separate from the general review. It answers a different question, and a finding from it deserves a different owner. Codex Security itself, including what it reports and how findings enter triage, has its own page: Codex Security.

Write review rules Codex follows in AGENTS.md

OpenAI’s GitHub guide says Codex searches your repository for AGENTS.md files, and tells you: “Add a ## Code Review Rules section to the file closest to the code the rules govern” (read 2026-10-13). The guide named the section ## Review guidelines when this site checked it on 2026-08-28, so rename the heading in an older file. Keep the rules under that heading so humans and Codex both find them. Rules that name a path and a checkable condition work better than general advice, because you can tell afterwards whether Codex applied them.

## Code Review Rules

- Flag any new or changed HTTP handler under `src/api/` that does not call `requireSession()`.
- Flag any SQL built with string concatenation or template literals; parameterized queries only.
- Flag any change under `src/billing/` that has no matching change under `tests/billing/`.
- Flag a new dependency in `package.json` and state what it replaces or why nothing existing fits.
- Flag user-facing string changes in `src/i18n/en.json` that have no matching key in `src/i18n/pl.json`.
- Do not comment on formatting or import order; `dprint` and `oxlint` enforce those in CI.

The last rule matters as much as the others. Every comment Codex spends on something a linter already enforces is a comment a reviewer learns to skip.

For stricter rules in one part of a monorepo, add an AGENTS.md inside that package, for example packages/payments/AGENTS.md, with its own ## Code Review Rules section. Codex chains AGENTS.md files from the repository root down to the directory it works in, as the AGENTS.md guide explains. The sources we could check on 2026-09-26 did not say how a review of a pull request that spans several packages picks up nested files. The guide read on 2026-10-13 says to “Put repository-wide rules in the root AGENTS.md and service-specific rules in a nested file”, and that Codex “applies the root and more-specific guidance that covers each changed file”, so keep every rule that must always apply in the root file.

Treat the rules like code: they change through pull requests, and when Codex misses something that mattered, add a rule for it in the same pull request as the fix.

Start cloud tasks from issues and pull requests

@codex review and @codex security review are the review commands. OpenAI’s cloud guide, as read on 2026-08-28, listed GitHub, alongside the web, GitLab, Linear and Slack, as a place to start cloud work. The rewritten guide (checked 2026-10-12) no longer lists them: it describes tasks started from published cloud environments that you continue “from the web, mobile, or desktop app”. Starting a cloud task by mentioning @codex with an instruction on an issue or pull request is therefore unconfirmed on 2026-10-12; try it on a test pull request before you rely on it.

A mention is a prompt, so it follows the same rule as any other prompt: state the goal, the boundary and the evidence you expect back. A bare @codex fix this produces a diff you then have to read line by line to understand.

Copy-paste comment: fix a red pull request

@codex The CI run on this pull request is failing. Read the failing job's log, reproduce the failure in your environment, and fix the cause in the code under test. Do not skip, delete or loosen any test, and do not change CI configuration. In your reply, list the failing test names before and after your change and the command you ran to verify.

Copy-paste comment: implement an issue with acceptance criteria

@codex Implement this issue. Before writing code, restate the acceptance criteria from the issue as a numbered list. Add or update tests so that each criterion has at least one test that fails without your change and passes with it. Keep the change inside the modules the issue names. In your reply, map each criterion to its test name and paste the test command output.

You can follow each task in Codex on the web or from the terminal with codex cloud list. To try a task’s result on your machine before it reaches a pull request, run codex cloud diff TASK_ID to see it and codex cloud apply TASK_ID to apply it to your working tree.

Review locally before you push

The cheapest review is the one that runs before a pull request exists. Codex CLI 0.157.1 has a non-interactive codex review command, and /review does the same inside the TUI.

codex review --uncommitted                     # staged, unstaged and untracked changes
codex review --base main                       # this branch against main
codex review --commit "$(git rev-parse HEAD)"  # the last commit only
codex review "Review the changes on this branch against main. Apply the Code Review Rules section in AGENTS.md; report only findings you can point to a line for."

In 0.157.1 a custom prompt cannot be combined with --base, --uncommitted or --commit: the CLI exits with the argument '--base <BRANCH>' cannot be used with '[PROMPT]'. Use either a target flag or a prompt, not both. --commit takes a SHA, so resolve HEAD with git rev-parse first.

Running codex review --base main before git push catches what @codex review would catch, one round-trip earlier. The review pane and the local loop are covered in the Codex review workflow.

How do you verify Codex’s work without reading every line?

Codex’s review is one signal, not an approval, and a Codex fix is a proposal until the checks say otherwise. Decide who proves what before the first task runs:

Evidence	Produced by	What it proves	Who signs off
Required status checks (tests, type check, lint)	Your CI, on the pull request’s head commit	The change builds and the existing behaviour still passes	Nobody; the branch protection rule blocks the merge
New or changed tests mapped to acceptance criteria	Codex, asked for by the comments above	Each criterion has a test that fails without the change	The pull request author, by checking the mapping
@codex review findings, resolved or answered	Codex, guided by AGENTS.md	Your written rules were applied to this diff	The author resolves each thread
Review on risky paths	A human in CODEOWNERS for src/billing/, src/auth/, migrations	Someone accountable looked where a mistake is expensive	That code owner

Three GitHub settings make the table enforceable instead of a convention: a branch protection rule (or ruleset) on the default branch that requires status checks to pass, requires a pull request review, and requires review from code owners. With those on, a pull request that Codex opened, reviewed and “fixed” still cannot merge until CI is green and an accountable human has approved.

For the human half, the triage in reviewing an agent’s pull request without reading every line turns “read the diff” into a short sequence: spec delta, evidence, risk flags, changed tests, sampled hotspots.

What breaks when Codex runs on your GitHub repository?

@codex gets no response on a pull request. The GitHub app usually lacks access to that repository, or code review is not enabled for it. In GitHub, open the organization’s installed GitHub apps, check that the repository is in the app’s access list, then confirm code review is on for that repository in Codex’s settings. Post the comment again after changing either.

Tasks fail during setup, or report different test results than CI. The environment’s setup commands drift from CI’s. Rerun the smoke test from Smoke-test the environment from the terminal and copy the install and test commands from your CI workflow file into the environment, line for line.

Reviews are noisy, or miss what matters. Codex follows the rules it has. Remove style comments by naming the formatter and linter in AGENTS.md, and add a path-specific rule for every miss that reached main. After 10 pull requests, count how many Codex findings led to a code change; if fewer than half did, cut rules rather than add them.

A Codex fix turns CI green by weakening a test. It happens when the prompt did not forbid it. The required status check will not catch it, because the weakened test passes. Say “do not skip, delete or loosen any test” in the comment, and add a review rule that flags any diff removing assertions or adding .skip.

An outside contributor’s issue steers the agent. Assume that issue and pull request text can become prompt input for any task started from that thread. On public repositories, start tasks only from issues a maintainer has triaged, keep production secrets out of the environment, and restrict the environment’s internet access to what the setup needs (internet access settings).

Codex opens a pull request nobody asked for. Someone mentioned @codex with an open-ended instruction. Close it, then agree as a team that every @codex task comment states the acceptance criteria, as the prompts on this page do.

Where to go next with Codex on GitHub

Codex review workflow Review, refine and merge Codex's changes in the review pane and with /review before anything reaches GitHub.

Code review with Codex Deeper review rules, review strategies and review on every surface, from the CLI to pull requests.

Pull request automation Automate the pull request lifecycle from issue to merge with @codex and the GitHub Action.

CI/CD with the Codex GitHub Action Run Codex inside your own GitHub Actions workflow when review must happen in CI you control.

AI code review bots compared Codex review beside Claude Code's Code Review, Cursor Bugbot and third-party review bots.

Reviewing an agent's pull request The six-step triage a human runs instead of reading every line of an agent's diff.