Pull request automation with Codex

Pull request automation with Codex takes one change to merge in six evidence-producing stages: isolate it in a worktree, have Codex open a draft pull request with its evidence, pre-review it with codex review, review it on GitHub with @codex review, repair failing checks with a bounded @codex task, and merge under branch protection with a named human owner.

This page is for developers who run Codex every day and tech leads who own the merge rules. The pattern it fixes: Codex finishes a task before lunch, the pull request waits two days for a reviewer, the reviewer’s first question is “what was this supposed to do?”, and the follow-up commit breaks CI. Each wait is a handoff with no evidence attached. Commands were checked against Codex CLI 0.157.1 on 2026-09-26.

What you’ll walk away with from Codex pull request automation

A stage-by-stage map of who acts, what triggers them and what evidence each stage leaves behind.
A pull request template and a prompt that make Codex open a draft pull request with commands and exit codes, not adjectives.
A bounded @codex comment that fixes a red check without editing tests or CI, and a way to pull the result back to your machine.
CODEOWNERS and branch-protection rules that let routine changes merge on evidence and send risky ones to a named person.

Review rules and the rollout of automatic reviews live on code review with Codex. Running openai/codex-action in GitHub Actions lives on Codex in CI/CD. This page connects them into one pull request lifecycle.

How does a Codex pull request move from worktree to merge?

Every stage leaves an artifact a reviewer can check in seconds. If a stage produces nothing checkable, it is a wait, not a gate.

Stage	Who acts	Trigger	Evidence it leaves	Gate
1. Isolate	You	`git worktree add` or `codex --worktree`	A branch with one task on it	None
2. Open	Codex, in the session	The “open a draft PR” prompt	Pull request body with commands and exit codes	Your read of the body
3. Pre-review	Codex, locally	`codex review --base main` or `/review`	P0 to P3 findings, fixed before push	No open P0 or P1
4. Review	Codex on GitHub	`@codex review`, or automatic reviews	Review comments on the pull request	Threads resolved or answered
5. Repair	A Codex cloud task, or you locally	An `@codex` comment with an instruction	A fix plus the failing tests before and after; the cleanup pass re-runs the suite and updates the Evidence table	CI green on the new head
6. Merge	A named human for risky paths	Branch protection, `CODEOWNERS`	Approval, green required checks	Merge button, or auto-merge

The order matters. Cheap private checks (stage 3) run before public ones (stage 4), so reviewers never spend time on findings Codex could have fixed alone.

Start each change in its own worktree

A pull request should hold one task. Give each task its own branch and working directory so a second Codex session cannot mix its edits in. For work that will become a pull request, create a named branch from the start. In a terminal:

git fetch origin
git worktree add -b feat/notification-prefs ../app-notification-prefs origin/main
cd ../app-notification-prefs
codex

codex --worktree is faster for exploration, but its managed worktree starts on a detached HEAD, so you must create the branch before you push. Bootstrapping, cleanup and what a managed worktree carries over are covered in isolated Codex tasks with Git worktrees. The same rule holds in the Codex desktop app (codex app, macOS and Windows): one task per branch, and read the diff yourself before you ask Codex to open the pull request.

Have Codex open a draft pull request with its evidence

A reviewer reads the pull request body before the diff. Make the body answer the three questions a reviewer asks first: what was the intent, what proves it works, and which lines need a human. Commit this template once, and every pull request, from Codex or a person, starts from it.

## Intent
<!-- One sentence: the behaviour this change adds or fixes. Link the issue or spec. -->

## What changed
<!-- At most five bullets, each naming the files involved. -->

## Evidence
<!-- Each command that was run, with its exit code. No claims without a command. -->
| Command | Exit code |
| --- | --- |

## Risk paths touched
<!-- Migrations, auth, billing, public API, tests, CI config. Write "none" if none. -->

## Not covered by tests
<!-- Behaviour the tests do not check, written as the missing test. -->

Then ask Codex to fill it. Pushing and opening the pull request need the network, which Codex’s workspace sandbox does not grant (OpenAI’s codex-action README says so of the :workspace profile, read 2026-09-26). Expect an approval request for git push and gh pr create, or run those two commands yourself.

The task on this branch is complete. Prepare it for review:
1. Run the full test suite, the type check and the linter. Record each command and its
   exit code. If any fails, stop and show me the failure instead of opening a PR.
2. Run `git diff --stat origin/main...HEAD` and list every changed file under
   migrations/, src/auth/, src/billing/, src/api/, tests/ or .github/.
3. Commit any uncommitted work with a message in the imperative mood that says what
   the change does and why.
4. Push the branch to origin and open a DRAFT pull request against main with
   `gh pr create --draft --base main`, filling .github/pull_request_template.md:
   Intent, What changed, Evidence (the table of commands and exit codes from step 1),
   Risk paths touched (from step 2), Not covered by tests.
Do not claim any result you did not run. Print the pull request URL at the end.

A draft pull request cannot be merged and does not request code-owner reviews until you mark it ready with gh pr ready. Read the body, not the diff: if the Evidence table is empty or lists a command you do not recognise, send it back before anyone else looks.

Get a first review before a human looks

Run Codex’s reviewer on the branch before you mark the pull request ready. From the terminal:

codex review --base main

Inside a session, /review does the same interactively. codex review --uncommitted reviews work you have not committed yet, and --commit SHA reviews one commit. In 0.157.1 a scope flag such as --base cannot be combined with a custom prompt, so put the focus in AGENTS.md: OpenAI’s GitHub guide reads custom review rules from it (read 2026-08-28), and a local Codex run in a trusted project loads it before doing any work. Fix each P0 and P1 finding, push, then mark the pull request ready.

On GitHub, comment on the pull request:

@codex review

OpenAI’s GitHub integration guide documents @codex review, @codex security review, automatic reviews for every new pull request, and review rules in AGENTS.md (last read 2026-08-28; the host has been unreachable from our environment since). The repository must be connected first; see connect Codex to GitHub. When to switch on automatic reviews, and how to test that the reviewer catches real bugs, is on code review with Codex.

Use one Codex review mechanism per repository. Automatic reviews, manual @codex review comments and a review job in openai/codex-action all post to the same pull request, and three reviewers repeating each other train the team to ignore all of them.

Fix a failing check with an @codex task

When CI goes red, a mention of @codex with an instruction starts a Codex cloud task that uses the pull request as context (OpenAI’s Codex cloud guide lists GitHub as a place to start cloud work, read 2026-08-28). The instruction is a prompt, so give it a goal, a boundary and the evidence you want back. A bare “fix CI” invites the fastest route to green, which is often a weakened test.

@codex The "test" job on this pull request fails. Read that job's log, reproduce the
failure in your environment, and fix the cause in the code under test. Do not edit,
skip or delete any test, do not change anything under .github/, and do not touch
files this pull request does not already change unless the root cause is there. In
your reply, list the failing test names before and after your change, the command
you ran to verify, and the root cause in two sentences.

Codex cloud tasks can be inspected from the terminal with codex cloud, which is [EXPERIMENTAL] in 0.157.1. To pull a task’s result onto your branch, verify it locally and push it yourself:

codex cloud list --limit 5          # find the task ID
codex cloud diff TASK_ID            # read the patch
codex cloud apply TASK_ID           # apply it to your working tree
npm test && git add -A && git commit -m "Fix failing notification preference test" && git push

TASK_ID is the identifier codex cloud list prints. Replace npm test with the command that failed in CI.

If you would rather fix it locally, give the log to Codex yourself. The GitHub CLI prints only the failing steps with gh run view RUN_ID --log-failed, where RUN_ID comes from gh pr checks.

CI failed on this branch. Run `gh pr checks` to find the failing run, then
`gh run view <run id> --log-failed` and save the output to /tmp/ci-failure.log.
Reproduce the failure locally with the same command CI ran. Fix the root cause with
the smallest change. Do not edit tests to make them pass and do not touch .github/.
Run the failing command again and the full suite after it, report both exit codes,
and commit with a message that names the root cause. Do not push.

For failures you want fixed without anyone commenting, a workflow_run job with openai/codex-action can propose the patch as a draft pull request. That setup, split so the job that runs Codex never holds a write token, is in let Codex propose a fix when CI fails.

Clean up the branch before you ask a human

The human reviewer’s time goes furthest when the leftovers of an agent session are gone: debug output, dead code, TODOs, tests that only check that a function was called. Run this in a Codex session on the pull request branch after the review findings are fixed.

Compare this branch with origin/main and make it ready for a human reviewer.
Fix, then re-run the test suite after each category:
1. console.log, print or debugger statements added on this branch.
2. TODO or FIXME comments added on this branch: resolve them or list them in the
   pull request body under "Not covered by tests" with a reason.
3. Unused imports, unused functions and commented-out code added on this branch.
4. New tests that assert only that a mock was called: add an assertion on the
   returned value or the stored state.
Then update the pull request body's Evidence table with the final commands and exit
codes. Do not change behaviour, public signatures or files outside this branch's diff.

Merge on evidence, not on a green review

A clean Codex review means the reviewer found nothing it was looking for. It does not mean the change is correct. The merge decision rests on checks that fail when the behaviour is wrong, plus a human signature where the cost of a mistake is high.

Require checks. In the branch protection rule (or ruleset) for main, require your test, type-check and lint jobs to pass, and require the branch to be up to date before merging.
Route risky paths to named owners. Commit a CODEOWNERS file and turn on “Require review from Code Owners”:
```
# .github/CODEOWNERS
/migrations/        @acme/data-owners
/src/auth/          @acme/security
/src/billing/       @acme/payments
/src/api/public/    @acme/api-owners
/tests/             @acme/tech-leads
/.github/           @acme/platform
```
Owning /tests/ and /.github/ matters most for agent work: a change that edits its own oracle or CI must never merge on the author’s say-so.
Let routine changes merge themselves. For a pull request that touches no owned path, has green required checks and has its Codex review threads resolved, the author can queue the merge:
Terminal window
```
gh pr merge --auto --squash
```
GitHub merges when the requirements are met, and not before.
Keep the evidence with the change. The pull request body, the review threads and the CI run stay attached to the merge commit. That record is what an incident review reads later.

What proves it	Checked by	Signs off
Behaviour works	Tests in required CI checks	CI
Types and style hold	Type check and lint in required checks	CI
No known defect class slipped in	Codex review against `AGENTS.md` rules	Author resolves every thread
Intent matches the change	Pull request body’s Intent and Risk paths	Reviewer, reading the body
Risky paths are right	Code owner review	The named owner

The reviewer’s job becomes reading the body and the risk list, then the diff of owned paths only. The full triage is in reviewing an agent’s pull request without reading every line, and the contract every agent pull request should carry is the evidence bundle.

If Codex should read pull requests, reviews and Actions logs through tools rather than the gh CLI, add GitHub’s MCP server (command from GitHub’s install guide; flags checked against codex mcp add --help in 0.157.1 on 2026-09-26):

codex mcp add github --url https://api.githubcopilot.com/mcp/ --bearer-token-env-var GITHUB_PAT_TOKEN

gh covers the same ground with fewer tokens; setup, toolset scoping and read-only mode are on the GitHub MCP server page.

What breaks in Codex pull request automation?

Codex cannot push or open the pull request. The workspace sandbox has no network, or gh is not logged in. Approve the git push and gh pr create requests when Codex asks, or run them yourself. Check gh auth status before you blame the sandbox.

The pull request conflicts with main. The worktree was cut from an old base. In the worktree, run git fetch origin && git rebase origin/main, ask Codex to re-run the full suite and update the Evidence table, then git push --force-with-lease. Re-request @codex review after the push, because comments from before the rebase point at old lines.

The @codex fix makes CI green by weakening a test. Reject the task’s result; do not apply it. Re-post the comment with the “do not edit, skip or delete any test” boundary, and make sure CODEOWNERS covers /tests/ so the change cannot merge without a tech lead even if someone applies it.

The pull request body claims results nobody ran. The Evidence table lists a command with exit code 0, but CI fails on the same command. Treat CI as the source of truth, send the pull request back, and add “Do not claim any result you did not run” to the prompt your team uses. To make that mechanical, adopt the evidence bundle, which shows how to make incomplete evidence fail CI.

@codex review gets no reply. Code review is not enabled for the repository, or the GitHub connection cannot see it. Re-check both in connect Codex to GitHub, then post the comment again.

Three reviewers, one pull request. Automatic reviews, a manual @codex review and a CI review job all posted. Keep one: automatic reviews once the rules are tuned, or the CI job if you need the result as a required check. Remove the others.

A fork’s pull request runs Codex with your API key. A review job that checks out a contributor’s branch reads that branch’s AGENTS.md, which steers the run. GitHub already withholds secrets from pull_request runs on forks, so a pull_request review job cannot run Codex there at all; review fork pull requests by hand. The risk is a pull_request_target or workflow_run job that checks out the fork’s head ref with secrets available, where its hooks, .codex/ config and AGENTS.md run or are read next to your key. A maintainer label does not fix that, because the contributor can push new commits after the label is applied. If you must use such a trigger, check out the workflow’s prompt and scripts from the default branch, put the fork’s commit in a separate directory that Codex only reads under the :read-only profile, load no project config, hooks or AGENTS.md from it, and keep the job at contents: read; the hardening rules are in how to lock down the Codex GitHub Action.

Where to go next with Codex pull requests

Code review with Codex Write AGENTS.md review rules, gate pushes on P0 and P1 findings, and test the reviewer with seeded bugs.

Run Codex in CI/CD with the GitHub Action Review, security gates and CI auto-fix jobs with openai/codex-action, hardened for secrets.

Codex multi-agent workflows Run several worktree tasks at once and merge their pull requests in a safe order.

Codex in Slack and Linear Start the task that becomes a pull request from an issue or a chat thread.

Using Claude Code for the same lifecycle? See review automation with Claude Code.