feat(ci): implement automated code review via GitHub Actions #101
Description
Context
Governance decided that code review belongs in CI/CD infrastructure, not in the methodology skills pipeline (#20). This issue captures the infrastructure implementation: a GitHub Actions workflow that runs automated code review on every PR.
The Codex GitHub App is already configured for auto-review on this repository. This issue is about having the review workflow committed as code — auditable, version-controlled, and iteratable — rather than relying solely on the app's implicit behavior.
Approach
Use the openai/codex-action@v1 GitHub Action to run Codex review in read-only sandbox mode on PR events. This is documented in OpenAI's published playbook for building code review with the Codex SDK.
Key design decisions
- Infrastructure, not methodology. This is a
.github/workflows/file, not a skill. The pipeline contract says "work must be reviewed before landing" — this workflow satisfies that requirement automatically. - Read-only sandbox. The review workflow reads code and posts comments. It does not modify files, push commits, or have network access beyond the GitHub API. This prevents credential exfiltration.
- AGENTS.md as review guidelines. Codex automatically discovers
AGENTS.mdfiles in the repo and follows any review guidelines defined there. This means review criteria are version-controlled alongside the code they govern. - Structured output. Use a JSON output schema for machine-parseable review findings (title, body, confidence score, priority, code location with file path and line range). This enables inline PR comments rather than monolithic review blocks.
Implementation sketch
name: Codex Code Review
on:
pull_request:
types: [opened, synchronize, reopened, ready_for_review]
permissions:
contents: read
pull-requests: write
jobs:
review:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v5
with:
ref: refs/pull/${{ github.event.pull_request.number }}/merge
fetch-depth: 0
- name: Run Codex review
uses: openai/codex-action@v1
with:
openai-api-key: ${{ secrets.OPENAI_API_KEY }}
prompt-file: .github/codex/prompts/review.md
output-file: codex-output.md
output-schema-file: .github/codex/review-schema.json
sandbox: read-only
safety-strategy: drop-sudo
- name: Post findings as inline PR comments
# Parse structured output and post via GitHub APIFuture consideration: Claude auto-fix chain
Consider chaining a Claude-based action after Codex review to auto-fix review findings. This would create a review → fix → re-review loop. This is a follow-on enhancement, not in scope for the initial implementation.
Deliverables
-
.github/workflows/code-review.yml— the review workflow -
.github/codex/prompts/review.md— review prompt referencing AGENTS.md conventions and groundwork's behavior-contract methodology -
.github/codex/review-schema.json— structured output schema for findings -
AGENTS.mdreview guidelines section (if not already present) — project-specific review criteria -
OPENAI_API_KEYsecret configured in repository settings - Verification: workflow triggers on a test PR and produces inline review comments
Acceptance criteria
- Workflow runs automatically on PR open/sync/reopen events
- Review runs in read-only sandbox — no file modifications, no network access beyond GitHub API
- Findings are posted as inline PR comments with file path and line numbers
- Review prompt references AGENTS.md for project-specific guidelines
- Workflow file is committed to
.github/workflows/(auditable, version-controlled)
References
- chore: reconcile code-review-as-infrastructure decision across project artifacts #20 — governance decision: code review is infrastructure, not methodology
- OpenAI Codex code review cookbook
openai/codex-action@v1— official GitHub Action- AGENTS.md configuration — how Codex discovers review guidelines