OpenAI Codex cloud agents for PR automation (L4)
Wire OpenAI Codex (the 2025 cloud coding agent) to your GitHub. Triage incoming issues, propose fixes as draft PRs, run tests in sandboxed environments, and ping the on-call engineer when ready for review. Your repository now has a 24/7 junior contributor.
The steps
- 01
Set up Codex with repo scopes
Tool: Codex
Provision Codex with read+write access to a labelled subset of repos (start with non-customer-facing services). Use GitHub App-style scoped tokens, NOT a personal access token. Configure a sandbox runtime that mirrors your CI environment exactly. Owner: platform eng + security. Pitfall: giving Codex prod-credentials access "to verify", never. Sandbox only. DoD: Codex can clone, build, and run tests on a chosen repo end-to-end in its own sandbox.
- 02
Connect to issue tracker with label-based triggers
Tool: Linear
In Linear/Jira/GitHub Issues, create label "codex-attempt". When a triage human applies that label, Codex pulls the issue context, opens a draft PR within 15 min, and links the PR back to the issue. Do NOT auto-trigger on every new issue, you'll get PR spam and lose trust. Owner: eng ops. DoD: applying the label reliably produces a draft PR in <30 min.
- 03
Require human review + observability
Tool: GitHub
Branch protection: Codex PRs CANNOT auto-merge. A human reviewer must approve. Log every Codex run: input issue, files touched, tokens used, time, outcome. Build a weekly dashboard of (a) PRs opened, (b) merged, (c) abandoned, (d) cost. Owner: platform eng. Pitfall: skipping observability, within a month you'll have no idea where your OpenAI bill went. DoD: weekly Codex performance + cost report shared in eng all-hands.
- 04
Define the "agent contract"
Tool: Manual
Write a 1-page "What Codex is allowed to do" doc: scopes, repos, what counts as a good PR (passes tests, follows .cursorrules, includes a description, references the issue), what gets rejected (changes to migrations, secrets, deployment configs). Treat it like a job description for a contractor. Owner: VP Eng. DoD: doc is shared with the team; rejection criteria are encoded as PR-bot checks where possible.
Tools in this playbook
Next playbooks
Unfamiliar terms are defined in the AI and Revenue Dictionary. Related frameworks live in the framework library.