# Connect Codex to GitHub URL: https://developertoolkit.ai/en/codex/quick-start/github-integration/ Description: Connect Codex to GitHub: set up a cloud environment, turn on @codex review, write AGENTS.md review rules, start tasks from issues and gate merges on CI. 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](/en/codex/quick-start/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](/en/codex/quick-start/agents-md/). ## 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](https://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](/en/codex/automate/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`. ```bash 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** ```text 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: ```text @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: ```text @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](/en/codex/operate/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. ```markdown ## 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](/en/codex/quick-start/agents-md/) 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** ```text @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** ```text @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. ```bash 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 ' 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](/en/codex/quick-start/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](/en/workflows/ship/agent-pr-review/) 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](#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](/en/codex/automate/cloud-environments/)). **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](/en/codex/quick-start/review-workflow/) — Review, refine and merge Codex's changes in the review pane and with /review before anything reaches GitHub. - [Code review with Codex](/en/codex/ship/code-review/) — Deeper review rules, review strategies and review on every surface, from the CLI to pull requests. - [Pull request automation](/en/codex/ship/pr-automation/) — Automate the pull request lifecycle from issue to merge with @codex and the GitHub Action. - [CI/CD with the Codex GitHub Action](/en/codex/ship/ci-cd/) — Run Codex inside your own GitHub Actions workflow when review must happen in CI you control. - [AI code review bots compared](/en/ecosystem/observability/ai-code-review-bots/) — Codex review beside Claude Code's Code Review, Cursor Bugbot and third-party review bots. - [Reviewing an agent's pull request](/en/workflows/ship/agent-pr-review/) — The six-step triage a human runs instead of reading every line of an agent's diff.