OpenAI Codex GitHub Integration: The Complete Setup Guide

Codex github integration turns your repository into a place where an agent can pick up a task, write the code, run tests, and open a pull request without you leaving the GitHub UI. This guide walks through installing the Codex GitHub App, wiring it into GitHub Actions, triggering tasks from issue comments, and setting up automated code review on every pull request. By the end you will have a working pipeline where "@codex fix this" in a comment turns into a reviewed diff.

Codex ships in two forms that both talk to GitHub: the Codex CLI you run locally or in CI, and the hosted Codex cloud agent that connects directly to a repository through a GitHub App. Most teams end up using both, the CLI for interactive local work and the cloud agent for background tasks triggered from GitHub itself.

What the Codex GitHub Integration Actually Does

Before installing anything, it helps to know what capabilities you are turning on. The Codex GitHub App gives the agent three distinct entry points into your workflow:

• Task creation from issues and comments. Mentioning the agent in a comment (for example @codex implement the pagination fix described above) queues a cloud task scoped to that repository and branch.
• Automated pull request review. Once enabled on a repo, Codex reads the diff on every new or updated pull request and leaves inline comments plus a summary, similar to a human reviewer.
• CI-triggered runs. You can call the Codex CLI directly inside a GitHub Actions workflow, so a push, a label, or a scheduled cron can kick off a coding task, a refactor, or a test-generation pass.

Each of these is opt-in and scoped per repository, so you can turn on review without turning on task creation, or vice versa.

Installing the Codex GitHub App

The GitHub App is the piece that lets Codex see your repository, open branches, and comment on pull requests. Install it from your organization's GitHub settings:

1. Go to your GitHub organization (or personal account) settings and open GitHub Apps.
2. Search for the Codex app and click Install.
3. Choose Only select repositories and pick the ones you want Codex to touch. Avoid All repositories on a shared org account until you have tested the workflow on one repo.
4. Grant the requested permissions. Codex typically asks for read/write on contents, pull requests, and issues, plus read on checks so it can see CI status.

After installation, open the repository on the Codex side (CLI or web dashboard) and link it to the same GitHub repo. This link is what lets a cloud task know which branch to check out and where to push its commits.

codex login
codex repo link owner/your-repo

Confirm the link worked by listing connected repos:

codex repo list

You should see your repository with a status of connected.

Connecting a Repository and Setting Defaults

Once linked, Codex needs a few defaults so it does not guess at your conventions. Most teams add a small config file at the root of the repo, commonly AGENTS.md or .codex/config.toml, that describes how to build, test, and lint the project.

## AGENTS.md

### Setup
- Install deps with `npm install`
- Run the dev server with `npm run dev`

### Testing
- Run `npm test` before opening a PR
- Run `npm run lint` and fix any errors

### Conventions
- Use TypeScript strict mode
- Prefer named exports
- Do not touch files under `legacy/`

Codex reads this file automatically at the start of every task in the repo. This one file is usually the highest-leverage thing you can do to get better pull requests out of the agent, because it replaces guesswork with explicit instructions.

You can also scope a .codex/config.toml for lower-level settings such as which branch to base new work on and whether the agent should run tests before finishing a task.

[github]
base_branch = "main"
auto_pr = true
require_tests_pass = true

[sandbox]
network_access = "restricted"

require_tests_pass = true is worth turning on early. It forces Codex to run your test suite before it opens a pull request, which cuts down on PRs that fail CI on the first push.

Using Codex from GitHub Issues and PR Comments

With the app installed and the repo linked, the fastest way to trigger a task is a comment. Open an issue, describe the problem, and mention the agent:

@codex the /api/orders endpoint returns a 500 when the cart is empty.
Add a check that returns a 400 with a clear error message instead,
and add a test that covers the empty-cart case.

Codex picks up the comment, creates a new branch, makes the change, runs the test command from AGENTS.md, and opens a pull request that links back to the issue. You get a notification when the PR is ready, and the PR description includes a summary of what changed and why.

The same pattern works inside an existing pull request. If a reviewer leaves a comment like @codex address this feedback, Codex reads the surrounding diff and the comment thread, pushes a follow-up commit to the same branch, and replies once it is done.

A few practical tips for writing comments that produce good results:

• Be specific about the file or endpoint, not just the symptom.
• Mention any constraints ("do not change the public API", "keep backward compatibility with v1 clients").
• If you already know the fix, describe it directly. Codex is faster and more accurate when it does not have to search for the right approach.

Codex Code Review on Pull Requests

Automated review is the integration most teams turn on first because it needs zero behavior change from contributors. Once enabled, every pull request against the linked repository gets a pass from Codex before or alongside human reviewers.

Turn it on per repository from the Codex dashboard or with the CLI:

codex repo config owner/your-repo --enable-review

On each pull request, Codex will:

• Read the full diff plus enough surrounding context to understand the change.
• Leave inline comments on lines it has concerns about (missing null checks, unhandled errors, inconsistent naming, obvious logic bugs).
• Post a top-level summary comment describing the overall change and any risk areas.
• Optionally check the diff against rules you define in AGENTS.md, such as "no direct database calls from controllers."

Review comments are advisory. Nothing blocks a merge by default. If you want Codex review to act as a merge gate, combine it with a required status check in your branch protection rules, so a human still makes the final call but cannot merge until the automated pass has run.

You can scope what the agent focuses on with a review config block:

[review]
focus = ["security", "error-handling", "test-coverage"]
ignore_paths = ["*.generated.ts", "vendor/**"]
max_comments_per_pr = 15

ignore_paths matters more than it looks. Without it, Codex will happily leave comments on generated files or vendored code, which trains contributors to ignore its feedback. Scope it tightly to source you actually control.

Running Codex Tasks via GitHub Actions

For teams that want tighter control over when and how Codex runs, calling the CLI directly from a GitHub Actions workflow is more predictable than relying on comment triggers. This is also the pattern to use for scheduled or bulk work, like a nightly dependency-update pass or a repo-wide lint fix.

name: codex-maintenance
on:
  schedule:
    - cron: "0 3 * * 1"
  workflow_dispatch:

jobs:
  run-codex:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Install Codex CLI
        run: npm install -g @openai/codex-cli

      - name: Run Codex task
        env:
          OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
        run: |
          codex exec "Update outdated npm dependencies that have no breaking \
          changes, run the test suite, and open a pull request summarizing \
          what changed."

      - name: Upload logs
        if: always()
        uses: actions/upload-artifact@v4
        with:
          name: codex-run-log
          path: codex-run.log

A second common pattern runs Codex on every pull request that carries a specific label, useful for opt-in AI-assisted fixes without triggering on every PR:

name: codex-on-label
on:
  pull_request:
    types: [labeled]

jobs:
  fix-pr:
    if: github.event.label.name == 'codex-fix'
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          ref: ${{ github.event.pull_request.head.ref }}

      - name: Install Codex CLI
        run: npm install -g @openai/codex-cli

      - name: Apply requested fix
        env:
          OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
        run: codex exec "Read the PR description and resolve any failing checks."

      - name: Commit and push
        run: |
          git config user.name "codex-bot"
          git config user.email "codex-bot@users.noreply.github.com"
          git add -A
          git diff --cached --quiet || git commit -m "codex: apply automated fix"
          git push

This label-triggered workflow is a good middle ground: contributors keep control over when the agent runs, but the trigger itself lives in GitHub rather than requiring anyone to remember a CLI command.

Codex CLI vs Codex Cloud for GitHub Workflows

It is worth being deliberate about which surface handles which kind of work, because they behave differently.

• Codex CLI in Actions runs inside a container you control, with the exact dependencies your workflow installs. It is predictable, easy to debug from logs, and fits naturally into existing CI. Use it for scheduled maintenance, lint sweeps, dependency bumps, and anything you want gated by existing branch protection rules.
• Codex cloud (the GitHub App) runs on infrastructure managed by OpenAI, triggered by comments or the dashboard, and is better suited to conversational, one-off tasks where someone describes a bug and expects a PR back. It also handles the automated review flow, which the CLI does not do on its own.

A reasonable default: keep code review and ad hoc "fix this" tasks on the cloud agent, and push repeatable, scheduled, or bulk operations into GitHub Actions where you already have logging, retries, and approval gates.

Handling Secrets and Permissions Safely

Because Codex can push commits and open pull requests, treat its credentials with the same care as any other CI identity.

• Store the API key in GitHub Actions secrets, never in the repository or in AGENTS.md.
• Scope the GitHub App to only the repositories that need it. Do not install it org-wide by default.
• Set network_access = "restricted" in the sandbox config unless a task genuinely needs outbound network calls, such as fetching a package registry.
• Require a human review on any Codex-authored pull request before merge, even with require_tests_pass = true enabled. Passing tests is not the same as a correct or safe change.
• Rotate the API key on the same schedule you rotate other CI secrets, and check the Codex dashboard's audit log periodically for unexpected task runs.

If you run Codex in a monorepo, use ignore_paths and repo-level permission scoping to keep it away from infrastructure-as-code directories or anything that provisions cloud resources. An agent that can open a PR against your Terraform config is not necessarily an agent you want opening that PR unsupervised.

Common Pitfalls

A few issues come up repeatedly when teams first wire this up:

• Missing `AGENTS.md` leads to noisy PRs. Without explicit build and test commands, Codex falls back to guessing your project's conventions, and the first few pull requests often need real rework. Write the file before you turn on task creation.
• No branch protection means low-quality merges slip through. Automated review comments are advisory only. If nobody is required to read them, they get ignored the same way a bot's comments always do.
• Overly broad `network_access` in shared runners. If your GitHub Actions runners are shared across teams, leaving network access unrestricted on a Codex task can let it pull unexpected dependencies. Keep it restricted and allowlist specific registries if needed.
• Triggering on every pull request instead of a label. Running Codex on every single PR update can get noisy fast, especially on active repos. Start with the label-gated workflow above and expand once the team trusts the output.
• Not scoping `ignore_paths` for generated code. Codex will review generated files literally as written, and comments on autogenerated code are almost always unhelpful. Exclude them up front.

FAQ

Does Codex need write access to my repository to work? Yes, for task creation and pull request review it needs read access to contents and issues plus write access to open branches and pull requests. If you only want review comments without any commits, most integrations still require the same base permission set, but you can disable auto_pr so it never pushes code on its own.

Can Codex merge pull requests automatically? Not by default, and this is intentional. Codex opens pull requests but merging is a separate action gated by your branch protection rules. You can configure auto-merge in GitHub itself once required checks pass, but that is a GitHub setting, not something Codex controls directly.

What happens if the linked repository has protected branches? Codex pushes to a new branch rather than main or any protected branch, then opens a pull request the normal way. Branch protection rules apply to that PR exactly as they would for a human contributor.

How is this different from just using the Codex CLI locally? Locally you drive the agent interactively from your terminal and review changes before committing. The GitHub integration adds triggers that do not require you to be at your keyboard: comments, labels, schedules, and automated review all fire without a human starting the session.

Can I use Codex GitHub integration with private repositories? Yes. The GitHub App works with private repositories the same way it works with public ones, as long as it is installed with access to that repository specifically. Nothing about the integration requires the repo to be public.

Does the automated review replace human code review? No. Treat it as a fast first pass that catches obvious issues before a human spends time on the diff. Security-sensitive or architecturally significant changes still need a human reviewer regardless of what the automated pass says.

What if a Codex task fails partway through, does it leave a broken branch behind? Failed tasks typically leave their working branch in place without opening a pull request, so nothing merges automatically from a broken run. Check the task log in the dashboard or the Actions run log to see where it stopped, then either rerun the task with clearer instructions or finish the branch manually.