Codex: Codex GitHub Integration
Last updated: 2026-08-31
Codex's GitHub integration is its core ecosystem advantage, enabling a fully automated workflow from Issue to PR.
📋 Prerequisites: Understanding Git and GitHub basic operations
1. What You Will Learn
- GitHub integration configuration
- Issue → PR automation
- PR review and comments
- Branch management strategies
2. GitHub Integration Configuration
(1) Authorize Codex
TEXT
📖 Display only
1. Select "Connect GitHub" in Codex settings
2. Authorize Codex to access your GitHub account
3. Choose authorization scope:
- Public repos
- All repos (including private)
- Selected repos
(2) CLI Configuration
BASH
# GitHub Token
export GITHUB_TOKEN="ghp_xxx"
# Or configure in auth.json
cat >> ~/.codex/auth.json << 'EOF'
{
"GITHUB_TOKEN": "ghp_xxx"
}
EOF
3. Issue → PR Automation
(1) Create Task from Issue
TEXT
📖 Display only
> Fix Issue #15: White screen after user login
# Codex automatically:
→ Reads Issue #15 description
→ Creates branch fix/issue-15
→ Analyzes root cause
→ Fixes code
→ Runs tests
→ Creates PR #16
→ Links Issue #15
→ Comments "Fixed in #16"
(2) Batch Process Issues
TEXT
📖 Display only
> Process all Issues labeled "good-first-issue"
# Codex processes each:
→ Issue #12: Fix typo → PR #13
→ Issue #14: Add missing type annotations → PR #15
→ Issue #18: Supplement API documentation → PR #17
▶ Example 1: Alice's Issue Processing Flow
TEXT
📖 Display only
# Alice's GitHub workflow
1. Community submits Issue → tagged "bug"
2. Alice in Codex: "Fix all P1 bugs"
3. Codex processes each:
- Creates fix branch
- Modifies code
- Runs tests
- Creates PR
- Links Issue
4. Alice reviews PR → Merges
5. Issue auto-closes
Processing efficiency: from 3 Issues/person/day up to 15
4. PR Automation
(1) Auto-create PR
After Codex completes code modifications, it automatically creates a PR:
TEXT
📖 Display only
PR Title: fix: resolve login white screen issue
Branch: codex/fix-issue-15
Base: main
Changes:
- src/auth/login.ts: Added error boundary handling
- src/components/Login.tsx: Fixed state management bug
- tests/auth.test.ts: Added 3 new test cases
Test Results: ✅ 45/45 passed
(2) PR Description Template
Define PR description format in AGENTS.md:
MARKDOWN
## PR Rules
PR description must include:
- Change description
- Linked Issue
- Test results
- Screenshots (if UI changes)
(3) Auto Review
TEXT
📖 Display only
> Review PR #42
# Codex output:
## Code Review Report
### 🔴 Critical
- src/api.ts:45 - SQL concatenation, injection risk
### 🟡 Medium
- src/utils.ts:23 - Unhandled Promise rejection
- src/auth.ts:67 - Overly permissive CORS configuration
### 🟢 Suggestions
- src/models.ts:12 - Type definition can be simplified
- tests/api.test.ts - Missing edge case tests
### Summary
- 1 critical issue must be fixed before merging
- 2 medium issues recommended to fix
- 2 improvement suggestions
5. Branch Management
(1) Auto Branch Naming
TEXT
📖 Display only
Codex auto-creates branches with naming convention:
- fix/issue-{number}-{description}
- feature/{description}
- refactor/{description}
(2) Branch Strategy
| Strategy | Description |
|---|---|
| From main | Each task creates a new branch from main |
| From develop | Tasks based on develop branch |
| From PR | Continue modifications on an existing PR |
▶ Example 2: Bob's Branch Workflow
TEXT
📖 Display only
# Bob's team uses Git Flow
1. Codex creates feature branch from develop
2. After feature complete, creates PR → develop
3. Code review passes → Merge
4. On release: develop → main
6. GitHub Actions Integration
YAML
# .github/workflows/codex-pr.yml
name: Codex PR Review
on:
pull_request:
types: [opened]
jobs:
auto-review:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: Codex Review
run: |
npm install -g @openai/codex
codex --quiet --sandbox readonly \
"Review this PR, output review report" \
> review.md
- name: Comment PR
uses: actions/github-script@v7
with:
script: |
const fs = require('fs');
const body = fs.readFileSync('review.md', 'utf8');
github.rest.issues.createComment({
issue_number: context.issue.number,
owner: context.repo.owner,
repo: context.repo.repo,
body
});
❓ FAQ
Q Can Codex handle private repositories?
A Yes, but you need to authorize Codex to access private repos. Select "All repos" during GitHub OAuth authorization.
Q Can Codex-created PRs be merged directly?
A Not recommended. Review code changes first, confirm tests pass, then merge. Set branch protection rules requiring PR review.
Q How do I limit Codex to only read certain repositories?
A Select "Selected repos" during GitHub OAuth authorization, only authorize necessary repositories.
Q Can Codex operate GitHub Actions?
A It can trigger and monitor Actions through MCP's GitHub server, but cannot directly modify workflow files.
Q Will multiple developers using Codex on the same repo cause conflicts?
A Not if modifying different files/branches. Each person should use an independent feature branch, avoid parallel operations on the same branch.
📖 Summary
- GitHub integration: Issue → Fix → PR → Review → Merge, fully automated
- PR auto-creation: includes change description, test results
- Code review: multi-dimensional — security/performance/style
- Branch management: auto-naming, created from target branch
- GitHub Actions integration: auto-review on PR
📝 Exercises
- Basic (⭐): Connect a GitHub repository, have Codex create a PR from an Issue.
- Intermediate (⭐⭐): Configure GitHub Actions for automatic PR review.
- Advanced (⭐⭐⭐): Design a complete GitHub workflow — Issue → auto-fix → PR → review → merge → notification, draw a flowchart.
