Commit Validation & Pre-Merge Checks

Commit validation uses Codex to verify that every commit in a PR meets your project's standards before merge. Unlike PR review (which comments on the diff), commit validation is a pass/fail gate: the PR cannot merge until Codex confirms compliance. Common validation checks include: commit messages follow Conventional Commits format, every new function has JSDoc comments, every new API endpoint has a corresponding test, and no TODO comments without a linked issue number.

The validation workflow analyzes the diff between the PR branch and the base branch, applies project rules from AGENTS.md, and produces a structured verdict. The verdict is binary: pass (all rules satisfied) or fail (with specific violations listed). This is more opinionated than review comments — it enforces standards rather than suggesting improvements. Use validation gates for objective, measurable rules and review comments for subjective guidance.

name: Codex Commit Validation
on:
  pull_request:
    types: [opened, synchronize]

jobs:
  validate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
      - uses: actions/setup-node@v4
        with:
          node-version: 22
      - run: npm install -g @openai/codex
      - name: Validate Commits
        env:
          OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
        run: |
          # Get the diff
          DIFF=$(git diff origin/${{ github.base_ref }}...HEAD)
          
          # Run Codex validation with strict rules
          codex --profile ci \
            --approval full-auto \
            "Validate this diff against project rules. Check: 
             1. All new functions have JSDoc comments
             2. All new API endpoints have tests
             3. No console.log statements in production code
             4. Commit messages follow Conventional Commits
             Output JSON: {pass: boolean, violations: string[]}" \
            < <(echo "$DIFF") > validation.json
          
          # Check result
          PASS=$(jq -r '.pass' validation.json)
          if [ "$PASS" != "true" ]; then
            echo "Validation FAILED:"
            jq -r '.violations[]' validation.json
            exit 1
          fi
          echo "Validation passed"

1. Define validation rules List every objective, measurable standard your team enforces. Each one becomes a validation check. Exclude subjective quality judgments.
2. Create the validation workflow Build a GitHub Actions workflow that runs Codex validation on every PR. Configure it as a required status check to block non-compliant merges.
3. Monitor false positives Track how often developers override validation failures. A high override rate means your rules are too strict or too ambiguous. Adjust until the false positive rate is below 5%.