stack/docs/CODEX-SETUP.md

Codex AI Review Setup for Mosaic Stack

Added: 2026-02-07 Status: Ready for activation

What Was Added

1. Woodpecker CI Pipeline

.woodpecker/
├── README.md                           # Setup and usage guide
├── codex-review.yml                    # CI pipeline configuration
└── schemas/
    ├── code-review-schema.json         # Code review output schema
    └── security-review-schema.json     # Security review output schema

The pipeline provides:

• ✅ AI-powered code quality review (correctness, testing, performance)
• ✅ AI-powered security review (OWASP Top 10, secrets, injection)
• ✅ Structured JSON output with actionable findings
• ✅ Automatic PR blocking on critical issues

2. Local Testing Scripts

Global scripts at ~/.claude/scripts/codex/ are available for local testing:

• codex-code-review.sh — Code quality review
• codex-security-review.sh — Security vulnerability review

Prerequisites

Required Tools (for local testing)

# Check if installed
codex --version   # OpenAI Codex CLI
jq --version      # JSON processor

Installation

Codex CLI:

npm i -g @openai/codex
codex  # Authenticate on first run

jq:

# Arch Linux
sudo pacman -S jq

# Debian/Ubuntu
sudo apt install jq

Usage

Local Testing (Before Committing)

cd ~/src/mosaic-stack

# Review uncommitted changes
~/.claude/scripts/codex/codex-code-review.sh --uncommitted
~/.claude/scripts/codex/codex-security-review.sh --uncommitted

# Review against main branch
~/.claude/scripts/codex/codex-code-review.sh -b main
~/.claude/scripts/codex/codex-security-review.sh -b main

# Review specific commit
~/.claude/scripts/codex/codex-code-review.sh -c abc123f

# Save results to file
~/.claude/scripts/codex/codex-code-review.sh -b main -o review.json

CI Pipeline Activation

Step 1: Commit the Pipeline

cd ~/src/mosaic-stack
git add .woodpecker/ CODEX-SETUP.md
git commit -m "feat: Add Codex AI review pipeline for automated code/security reviews

Add Woodpecker CI pipeline for automated code quality and security reviews
on every pull request using OpenAI's Codex CLI.

Features:
- Code quality review (correctness, testing, performance, code quality)
- Security review (OWASP Top 10, secrets, injection, auth gaps)
- Parallel execution for fast feedback
- Fails on blockers or critical/high security findings
- Structured JSON output

Includes:
- .woodpecker/codex-review.yml — CI pipeline configuration
- .woodpecker/schemas/ — JSON schemas for structured output
- CODEX-SETUP.md — Setup documentation

To activate:
1. Add 'codex_api_key' secret to Woodpecker CI
2. Create a PR to trigger the pipeline
3. Review findings in CI logs

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>"
git push

Step 2: Add Woodpecker Secret

1. Go to https://ci.mosaicstack.dev
2. Navigate to mosaic/stack repository
3. Settings → Secrets
4. Add new secret:
   • Name: codex_api_key
   • Value: (your OpenAI API key)
   • Events: Pull Request, Manual

Step 3: Test the Pipeline

Create a test PR:

git checkout -b test/codex-review
echo "# Test" >> README.md
git add README.md
git commit -m "test: Trigger Codex review pipeline"
git push -u origin test/codex-review

# Create PR via gh or tea CLI
gh pr create --title "Test: Codex Review Pipeline" --body "Testing automated reviews"

What Gets Reviewed

Code Quality Review

• ✓ Correctness — Logic errors, edge cases, error handling
• ✓ Code Quality — Complexity, duplication, naming conventions
• ✓ Testing — Coverage, test quality, flaky tests
• ✓ Performance — N+1 queries, blocking operations
• ✓ Dependencies — Deprecated packages
• ✓ Documentation — Complex logic comments, API docs

Severity levels: blocker, should-fix, suggestion

Security Review

• ✓ OWASP Top 10 — Injection, XSS, CSRF, auth bypass, etc.
• ✓ Secrets Detection — Hardcoded credentials, API keys
• ✓ Input Validation — Missing validation at boundaries
• ✓ Auth/Authz — Missing checks, privilege escalation
• ✓ Data Exposure — Sensitive data in logs
• ✓ Supply Chain — Vulnerable dependencies

Severity levels: critical, high, medium, low Includes: CWE IDs, OWASP categories, remediation steps

Pipeline Behavior

• Triggers: Every pull request
• Runs: Code review + Security review (in parallel)
• Duration: ~15-60 seconds per review (depends on diff size)
• Fails if:
  • Code review finds blockers
  • Security review finds critical or high severity issues
• Output: Structured JSON in CI logs + markdown summary

Integration with Existing CI

The Codex review pipeline runs independently from the main .woodpecker.yml:

Main pipeline (.woodpecker.yml)

• Type checking (TypeScript)
• Linting (ESLint)
• Unit tests (Vitest)
• Integration tests (Playwright)
• Docker builds

Codex pipeline (.woodpecker/codex-review.yml)

• AI-powered code quality review
• AI-powered security review

Both run in parallel on PRs. A PR must pass BOTH to be mergeable.

Troubleshooting

"codex: command not found" locally

npm i -g @openai/codex

"codex: command not found" in CI

Check the node image version in .woodpecker/codex-review.yml (currently node:22-slim).

Pipeline passes but should fail

Check the failure thresholds in .woodpecker/codex-review.yml:

• Code review: BLOCKERS=$(jq '.stats.blockers // 0')
• Security review: CRITICAL=$(jq '.stats.critical // 0') HIGH=$(jq '.stats.high // 0')

Review takes too long

Large diffs (500+ lines) may take 2-3 minutes. Consider:

• Breaking up large PRs into smaller changes
• Using --base locally to preview review before pushing

Documentation

• Pipeline README: .woodpecker/README.md
• Global scripts README: ~/.claude/scripts/codex/README.md
• Codex CLI docs: https://developers.openai.com/codex/cli/

Next Steps

1. ✅ Pipeline files created
2. ⏳ Commit pipeline to repository
3. ⏳ Add codex_api_key secret to Woodpecker
4. ⏳ Test with a small PR
5. ⏳ Monitor findings and adjust thresholds if needed

---

This setup reuses the global Codex review infrastructure from ~/.claude/scripts/codex/, which is available across all repositories.