AI DeliveryPreview Learning Center

Real case: one repository, every file real

The AI SDLC on GitHub

A team, an agent that writes code, and the gates around it: context in CLAUDE.md, enforcement in hooks, roles in subagents, checks in Actions, review by Claude and by owners, rules on main. Built from one example project you can download.

Proves the stages: Build · Test · Release. Moved here from the test center, where the tests it runs still live.

The shape

The agent writes. The repository decides.

A team using Claude Code on GitHub does not need a new process; it needs the existing one made explicit and enforced by the repository, because an agent follows what is enforced and only reads what is suggested. Eight stages, each a file in the example project below.

  1. 1

    Spec

    A person owns the intent: docs/pricing.md, an issue, an OpenAPI schema. The tests are written to it, and the pull request template asks which one.

  2. 2

    Agent writes

    Claude Code in the repository, with CLAUDE.md as context and the hooks as enforcement; the testing subagents plan, generate, grade and fuzz.

  3. 3

    Early validation

    Before anyone reads the diff: check (format, tests), score (mutation, pass rates), judge (Claude's review). The hooks run the first of these after every edit.

  4. 4

    Pull request

    The template asks what changed, what proves it, who or what wrote it, and which tests were healed. Test Passports ride along.

  5. 5

    Actions

    Six jobs on every pull request, from the repository, not from memory. Each is a required status check.

  6. 6

    Review

    The code-review plugin posts inline findings; code owners of tests/, infra/ and .claude/ must approve; a person merges.

  7. 7

    Ruleset

    No merge without the checks, the owners' review, signed commits; no force pushes, no deletion of main.

  8. 8

    Nightly

    What does not fit a pull request: the 30-minute soak with its p95 gate, and the MCP gates against the test deployment.

The example project is acme-checkout: the pricing module, orders API, bot and checkout page from the Examples page, with the files that run them in a team. 68 files, all real; download them below.

The repository

Every file, as committed

Click a file to read it. The workflows were taken from the official documentation where one exists and are noted as such in their first lines; the hooks, agents, gates and passports are ours and ran against this code on 2026-10-25.

CLAUDE.md
# acme-checkout

A small checkout service: a pricing module, an orders API, a support bot and a checkout page.
This file is context for Claude Code; the hooks in `.claude/settings.json` are the enforcement.

## Commands

- Unit and property tests: `pytest -q`
- Grade the tests: `mutmut run && python scripts/mutation_gate.py` (fails below 80 percent killed)
- Contract tests: `schemathesis run http://127.0.0.1:8081/openapi.json --max-examples 200`
  (start the API first with `uvicorn acme.app:app --port 8081 --app-dir src`)
- End to end: `cd e2e && npx playwright test`
- Evals: `cd evals && npx promptfoo eval --no-cache`
- Lint and format: `ruff check . && ruff format .`

## Rules for changes

- Every new function ships with tests, and we keep the tests that kill mutants. A test that
  kills nothing is deleted, not kept for the coverage number.
- Property tests state invariants (never, always, round trip), not examples.
- The expected value in an assertion comes from `docs/` or from a person, never from running the
  code and pasting what it printed. If the spec is silent, ask in the pull request.
- A healed Playwright test is a code change: commit it on its own with the reason in the message.
- Never run `terraform apply`, `tofu apply`, `git push --force` or delete directories; CI applies
  and people merge. The PreToolUse hook blocks these anyway.
- Secrets come from the environment and GitHub Secrets, never from the repository.
- Each test file carries a Test Passport (`tests/*.passport.yaml`): who or what wrote it, which
  spec it serves, where its expected values came from, who reviewed it, and its evidence. Update
  the passport in the same pull request as the test.

## Pull requests

- One concern per pull request. Say what you changed and what proves it.
- Fill in the AI disclosure line of the pull request template.
- Code owners review `infra/`, `tests/` and `.claude/` (see `.github/CODEOWNERS`).

Made in your browser from the files above; nothing is sent anywhere.

Context and enforcement

CLAUDE.md is what the agent reads. Hooks are what always happens.

The official memory docs are plain about it: CLAUDE.md is guidance the model follows, and when something must happen every time, a hook enforces it. The project uses both, for different things.

CLAUDE.md: context

  • Lives at ./CLAUDE.md (or ./.claude/CLAUDE.md) for the project, ~/.claude/CLAUDE.md for the person, CLAUDE.local.md for the person's notes on this project, ignored by git.
  • Keep it under 200 lines; split with .claude/rules/ and @path imports when it grows.
  • What goes in: the commands, the conventions, the "never" list, where the spec lives. What stays out: anything that needs to be enforced.

Claude Code memory: CLAUDE.md

Hooks: enforcement

  • PostToolUse with matcher Edit|Write: the file path arrives as JSON on stdin (tool_input.file_path); the hook formats it and runs the fast tests, so the agent sees a failure within seconds of causing it.
  • PreToolUse with matcher Bash: the command arrives as tool_input.command; exit code 2 blocks it and stderr goes back to the agent as the reason. That is how terraform apply and git push --force never run from the agent's shell.
  • Hooks are of type command, http, mcp_tool, prompt or agent; the project uses commands, kept in .claude/hooks/ so they are reviewed like code.

Claude Code hooks guide

Subagents: roles with their own tools

  • Markdown files in .claude/agents/ with frontmatter: name, description, tools (or disallowedTools), model, permissionMode, maxTurns.
  • The mutation grader has Read, Grep, Glob and Bash and a rule never to edit src/; the contract fuzzer may write tests and nothing else.
  • Playwright's planner, generator and healer are generated with npx playwright init-agents --loop=claude, together with the .mcp.json that gives them a browser; regenerate on upgrade rather than editing.

Claude Code subagents · Playwright test agents

Context

CLAUDE.md
## Rules for changes

- Every new function ships with tests, and we keep the tests that kill mutants. A test that
  kills nothing is deleted, not kept for the coverage number.
- Property tests state invariants (never, always, round trip), not examples.
- The expected value in an assertion comes from `docs/` or from a person, never from running the
  code and pasting what it printed. If the spec is silent, ask in the pull request.
- A healed Playwright test is a code change: commit it on its own with the reason in the message.
- Never run `terraform apply`, `tofu apply`, `git push --force` or delete directories; CI applies
  and people merge. The PreToolUse hook blocks these anyway.
- Secrets come from the environment and GitHub Secrets, never from the repository.
- Each test file carries a Test Passport (`tests/*.passport.yaml`): who or what wrote it, which
  spec it serves, where its expected values came from, who reviewed it, and its evidence. Update
  the passport in the same pull request as the test.

## Pull requests

Enforcement

.claude/hooks/guard.sh
#!/bin/bash
# PreToolUse for Bash: block the commands that must never run from an agent's shell. Exit code 2
# blocks the tool call and sends stderr back to Claude as the reason.
COMMAND=$(jq -r '.tool_input.command // empty')
if echo "$COMMAND" | grep -qE '(^|[;&| ])(terraform|tofu) +apply|git +push +(-f|--force)|rm +-rf +(/|~|\.)( |$)|git +reset +--hard|--no-verify'; then
  echo "Blocked by .claude/hooks/guard.sh: '$COMMAND'. CI applies infrastructure and people merge; see CLAUDE.md." >&2
  exit 2
fi
exit 0

Check, score, judge

The six jobs every pull request passes

Deterministic checks first, then scores with a bar, then the judgment calls. The person who merges reads the scores and samples the judgments; the rest is the pipeline's job. Each job's name is a required status check in the ruleset, so the two files are checked against each other by this site's build.

Job (required check)KindWhat runsWhat it proves
lint, unit, property, APIcheckruff, pytest with Hypothesis, the API regression testsThe code runs and the stated invariants hold. The fast half runs in the PostToolUse hook too, so the agent sees failures before the pull request exists.
mutation scorescoremutmut, scripts/mutation_gate.py at 80 percentThe tests prove something: a suite that kills fewer than four mutants in five fails the build, whoever wrote it.
Schemathesis against the OpenAPI schemacheckschemathesis run, 200 examples per operation, JUnit reportThe API keeps its contract. This is the job that would have caught the 500 on GET /orders/0.
Playwrightchecknpx playwright test, traces on failureThe checkout flow works as a user sees it. A healed locator is a code change reviewed like one.
promptfoo evalsscorenpx promptfoo eval, deterministic assertions, exit code 100 on failureThe bot states the facts and keeps its persona. The provider here is deterministic; a real one needs the pass-rate gate from the nondeterministic page.
Test Passportscheckscripts/passport_check.py tests --min-grade BEvery test file says who wrote it, to which spec, with what evidence, and clears a B.
.github/workflows/ci.yml
.github/workflows/ci.yml
# The gates every pull request passes before a person reads it: check, score, judge.
# Each job is a required status check in rulesets/main.json, so nothing merges without them.
name: CI
on:
  pull_request:
  push:
    branches: [main]
concurrency:
  group: ci-${{ github.ref }}
  cancel-in-progress: true
permissions:
  contents: read
jobs:
  check:
    name: lint, unit, property, API
    runs-on: ubuntu-latest
    timeout-minutes: 15
    steps:
      - uses: actions/checkout@v6
      - uses: actions/setup-python@v6
        with: { python-version: "3.12" }
      - run: pip install -e .[dev]
      - run: ruff check . && ruff format --check .
      - run: pytest --junitxml=results/junit-unit.xml
      - uses: actions/upload-artifact@v5
        if: always()
        with: { name: junit-unit, path: results/ }

  score:
    name: mutation score
    runs-on: ubuntu-latest
    timeout-minutes: 20
    steps:
      - uses: actions/checkout@v6
      - uses: actions/setup-python@v6
        with: { python-version: "3.12" }
      - run: pip install -e .[dev]
      - run: mutmut run
      - run: python scripts/mutation_gate.py
        env: { MUTATION_MIN_SCORE: "0.80" }

  contract:
    name: Schemathesis against the OpenAPI schema
    runs-on: ubuntu-latest
    timeout-minutes: 15
    steps:
      - uses: actions/checkout@v6
      - uses: actions/setup-python@v6
        with: { python-version: "3.12" }
      - run: pip install -e .[dev]
      - run: |
          uvicorn acme.app:app --port 8081 --app-dir src &
          for i in $(seq 1 30); do curl -sf http://127.0.0.1:8081/openapi.json > /dev/null && break; sleep 1; done
      - run: schemathesis run http://127.0.0.1:8081/openapi.json --max-examples 200 --continue-on-failure --report junit --report-dir results
      - uses: actions/upload-artifact@v5
        if: always()
        with: { name: junit-contract, path: results/ }

  e2e:
    name: Playwright
    runs-on: ubuntu-latest
    timeout-minutes: 20
    defaults: { run: { working-directory: e2e } }
    steps:
      - uses: actions/checkout@v6
      - uses: actions/setup-node@v6
        with: { node-version: 22 }
      - run: npm ci
      - run: npx playwright install --with-deps chromium
      - run: npx playwright test
      - uses: actions/upload-artifact@v5
        if: always()
        with: { name: playwright-results, path: e2e/results/ }

  evals:
    name: promptfoo evals
    runs-on: ubuntu-latest
    timeout-minutes: 10
    defaults: { run: { working-directory: evals } }
    steps:
      - uses: actions/checkout@v6
      - uses: actions/setup-node@v6
        with: { node-version: 22 }
      - uses: actions/setup-python@v6
        with: { python-version: "3.12" }
      # the provider here is deterministic, so no model key is needed; a real bot reads its key
      # from a GitHub Secret passed as env, never from the repository
      - run: npx --yes promptfoo@latest eval --no-cache --output results.json

  passports:
    name: Test Passports
    runs-on: ubuntu-latest
    timeout-minutes: 5
    steps:
      - uses: actions/checkout@v6
      - uses: actions/setup-python@v6
        with: { python-version: "3.12" }
      - run: pip install pyyaml
      - run: python scripts/passport_check.py tests --min-grade B
.github/workflows/nightly.yml: the soak and the MCP gates
.github/workflows/nightly.yml
# What does not belong on every pull request: the soak and the MCP gates, nightly against the
# test deployment. A threshold breach here opens an issue through the step summary.
name: Nightly
on:
  schedule:
    - cron: "17 3 * * *"
  workflow_dispatch:
permissions:
  contents: read
jobs:
  soak:
    runs-on: ubuntu-latest
    timeout-minutes: 60
    steps:
      - uses: actions/checkout@v6
      - uses: actions/setup-python@v6
        with: { python-version: "3.12" }
      - run: pip install -e .[dev]
      - run: |
          uvicorn acme.app:app --port 8081 --app-dir src &
          sleep 2
      # 30 minutes at a steady 15 users: the soak profile from the load example; p95 and the
      # failure ratio are read from the CSV by the step that follows
      - run: locust --headless --users 15 --spawn-rate 1 -H http://127.0.0.1:8081 -f tests/locustfile.py --run-time 30m --only-summary --csv results/soak
      - run: python scripts/soak_gate.py results/soak_stats.csv
  mcp-gates:
    runs-on: ubuntu-latest
    timeout-minutes: 10
    steps:
      - uses: actions/checkout@v6
      - uses: actions/setup-node@v6
        with: { node-version: 22 }
      - run: npm i --no-save @modelcontextprotocol/server-filesystem @modelcontextprotocol/inspector
      - run: |
          mkdir -p docs
          echo "refund policy: 30 days" > docs/policy.txt
          bash scripts/mcp_gates.sh
.github/workflows/deploy.yml: the push to main, from build to canary
.github/workflows/deploy.yml
# The second trigger: the push to main. Build once, attest, scan, deploy to staging through OIDC,
# verify where variance is allowed, wait for a person at the production environment, go out as a
# canary, draft the release notes. The animated version is on the Sample diagrams page.
name: Deploy
on:
  push:
    branches: [main]
concurrency:
  group: deploy-main
  cancel-in-progress: false   # a deploy in flight finishes; the next waits its turn
permissions:
  contents: read
jobs:
  build:
    name: build once, attest
    runs-on: ubuntu-latest
    timeout-minutes: 20
    permissions:
      contents: read
      packages: write
      id-token: write
      attestations: write
    outputs:
      image: ${{ steps.meta.outputs.image }}
    steps:
      - uses: actions/checkout@v6
      - uses: actions/setup-python@v6
        with: { python-version: "3.12" }
      - id: meta
        run: echo "image=ghcr.io/${{ github.repository }}:${{ github.sha }}" >> "$GITHUB_OUTPUT"
      - run: pip install build && python -m build
      - name: Generate artifact attestation
        uses: actions/attest@v4
        with:
          subject-path: 'dist/*'
      - run: echo "${{ secrets.GITHUB_TOKEN }}" | docker login ghcr.io -u "${{ github.actor }}" --password-stdin
      - run: docker build -t "${{ steps.meta.outputs.image }}" . && docker push "${{ steps.meta.outputs.image }}"
      - uses: actions/upload-artifact@v5
        with: { name: dist, path: dist/ }

  scan:
    name: scan
    needs: build
    runs-on: ubuntu-latest
    timeout-minutes: 15
    steps:
      - uses: actions/checkout@v6
      - uses: actions/setup-python@v6
        with: { python-version: "3.12" }
      - run: pip install checkov bandit
      - run: bandit -q -r src
      - run: checkov -d infra --framework terraform --quiet --compact --config-file infra/.checkov.yaml

  staging:
    name: deploy staging
    needs: [build, scan]
    runs-on: ubuntu-latest
    timeout-minutes: 15
    environment:
      name: staging
      url: https://staging.shop.example.test
    permissions:
      id-token: write
      contents: read
    steps:
      - uses: actions/checkout@v6
      # the OIDC token is exchanged for a short-lived credential; no cloud key is stored in GitHub
      - uses: aws-actions/configure-aws-credentials@v4
        with:
          role-to-assume: ${{ vars.STAGING_DEPLOY_ROLE }}
          aws-region: ca-central-1
      - run: ./deploy/deploy.sh staging "${{ needs.build.outputs.image }}"

  verify:
    name: verify in staging
    needs: [build, staging]
    runs-on: ubuntu-latest
    timeout-minutes: 30
    env:
      BASE_URL: https://staging.shop.example.test
    steps:
      - uses: actions/checkout@v6
      - uses: actions/setup-node@v6
        with: { node-version: 22 }
      - run: cd e2e && npm ci && npx playwright install --with-deps chromium && npx playwright test
      - uses: grafana/setup-k6-action@v1
      - run: k6 run load/smoke.js   # thresholds in the script: p(95)<500, failures<1%
      # the real model answers here; the pass rate, not zero failures, is the gate
      - run: cd evals && PROMPTFOO_PASS_RATE_THRESHOLD=95 npx --yes promptfoo@latest eval --no-cache --repeat 5

  production:
    name: deploy production
    needs: [build, verify]
    runs-on: ubuntu-latest
    timeout-minutes: 30
    environment:
      name: production   # required reviewers and the wait timer are set on the environment
      url: https://shop.example.test
    permissions:
      id-token: write
      contents: read
    steps:
      - uses: actions/checkout@v6
      - uses: aws-actions/configure-aws-credentials@v4
        with:
          role-to-assume: ${{ vars.PRODUCTION_DEPLOY_ROLE }}
          aws-region: ca-central-1
      - run: ./deploy/deploy.sh production "${{ needs.build.outputs.image }}" --canary 10
      - run: ./deploy/smoke.sh production
      - run: ./deploy/deploy.sh production "${{ needs.build.outputs.image }}" --all

  notes:
    name: release notes, drafted
    needs: production
    runs-on: ubuntu-latest
    timeout-minutes: 10
    permissions:
      contents: read
      issues: read
      id-token: write
    steps:
      - uses: anthropics/claude-code-action@v1
        with:
          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
          prompt: "Draft release notes for the commits on main since the last tag, grouped by area, one line each; a person will edit and publish them."
          claude_args: |
            --max-turns 5
            --allowedTools "mcp__github__list_commits"
Jenkinsfile: the same pipeline on Jenkins (not run here)
Jenkinsfile
// The same pipeline on Jenkins, as drawn on the Sample diagrams page. Declarative syntax; in a
// real setup the stages come from the shared library (vars/) and this file is a few lines.
// Written to the documented syntax (jenkins.io/doc/book/pipeline/syntax); not run here.
@Library('acme-pipeline@v3') _

pipeline {
  agent none   // every stage names its own agent; nothing runs on the controller
  options {
    timeout(time: 45, unit: 'MINUTES')
    disableConcurrentBuilds()
    buildDiscarder(logRotator(numToKeepStr: '30'))
  }
  environment {
    IMAGE = "ghcr.io/acme/checkout:${env.GIT_COMMIT.take(12)}"
  }
  stages {
    stage('Checkout') {
      agent { label 'linux' }
      steps { checkout scm; stash name: 'src', includes: '**/*' }
    }
    stage('Build') {
      agent { label 'linux' }
      steps { unstash 'src'; sh 'pip install -e .[dev] && python -m build'; stash name: 'dist', includes: 'dist/**' }
    }
    stage('Test') {
      parallel {
        stage('Unit and property') {
          agent { label 'linux' }
          steps { unstash 'src'; sh 'pytest --junitxml=results/junit.xml' }
          post { always { junit 'results/junit.xml' } }
        }
        stage('Static analysis') {
          agent { label 'linux' }
          steps { unstash 'src'; sh 'ruff check . && ruff format --check . && bandit -q -r src' }
        }
        stage('AI test generation') {
          agent { label 'linux' }
          when { changeRequest() }                     // pull requests only
          options { timeout(time: 10, unit: 'MINUTES') } // the budget
          environment { ANTHROPIC_API_KEY = credentials('anthropic-api-key') }
          steps {
            unstash 'src'
            // the agent proposes tests for the diff; mutation testing grades them; nothing is committed
            sh 'claude -p "Write pytest tests for the files changed in this pull request, to docs/ and never to the implementation." --max-turns 15 --allowedTools "Read,Grep,Glob,Write"'
            sh 'mutmut run && python scripts/mutation_gate.py'
            sh 'git diff > results/ai-tests.patch'
            archiveArtifacts artifacts: 'results/ai-tests.patch', allowEmptyArchive: true
          }
        }
      }
    }
    stage('Package and image') {
      agent { label 'linux' }
      environment { REGISTRY = credentials('ghcr-push') }   // REGISTRY_USR and REGISTRY_PSW
      steps {
        unstash 'src'; unstash 'dist'
        sh 'echo "$REGISTRY_PSW" | docker login ghcr.io -u "$REGISTRY_USR" --password-stdin'
        sh 'docker build -t "$IMAGE" . && docker push "$IMAGE"'
        archiveArtifacts artifacts: 'dist/*', fingerprint: true
      }
    }
    stage('Scan') {
      agent { label 'linux' }
      steps {
        unstash 'src'
        sh 'checkov -d infra --framework terraform --quiet --compact --config-file infra/.checkov.yaml'
        sh 'trivy image --exit-code 1 --severity HIGH,CRITICAL "$IMAGE"'
      }
    }
    stage('Deploy staging') {
      when { branch 'main' }
      agent { label 'deploy' }
      environment { KUBECONFIG = credentials('kubeconfig-staging') }
      steps { unstash 'src'; sh './deploy/deploy.sh staging "$IMAGE" --all' }
    }
    stage('Verify') {
      when { branch 'main' }
      parallel {
        stage('End to end') {
          agent { label 'linux' }
          steps { unstash 'src'; sh 'cd e2e && npm ci && npx playwright install --with-deps chromium && BASE_URL=https://staging.shop.example.test npx playwright test' }
        }
        stage('Load') {
          agent { label 'linux' }
          steps { unstash 'src'; sh 'BASE_URL=https://staging.shop.example.test k6 run load/smoke.js' }
        }
        stage('Evals') {
          agent { label 'linux' }
          steps { unstash 'src'; sh 'cd evals && PROMPTFOO_PASS_RATE_THRESHOLD=95 npx --yes promptfoo@latest eval --no-cache --repeat 5' }
        }
      }
    }
    stage('Approve production') {
      when { branch 'main' }
      agent none
      input {
        message 'Deploy this build to production?'
        ok 'Deploy'
        submitter 'release-managers'
        parameters { string(name: 'NOTES', defaultValue: '', description: 'Release notes, as reviewed') }
      }
      steps { echo "Approved. Notes: ${NOTES}" }
    }
    stage('Deploy production') {
      when { branch 'main' }
      agent { label 'deploy' }
      environment { KUBECONFIG = credentials('kubeconfig-production') }
      steps {
        unstash 'src'
        sh './deploy/deploy.sh production "$IMAGE" --canary 10'
        sh './deploy/smoke.sh production'
        sh './deploy/deploy.sh production "$IMAGE" --all'
      }
    }
  }
  post {
    failure {
      // the triage station: reads the console log and the JUnit report, comments on the pull request
      script { node('linux') { unstash 'src'; sh 'python scripts/triage.py --build "$BUILD_URL" --junit results/' } }
    }
    success {
      script { if (env.BRANCH_NAME == 'main') { node('linux') { unstash 'src'; sh 'python scripts/release_notes.py --draft' } } }
    }
    always { echo "${currentBuild.currentResult}: ${env.JOB_NAME} #${env.BUILD_NUMBER}" }
  }
}

Both pipelines are drawn and animated on the Sample diagrams page.

Claude on the pull request

Two workflows from the official docs, and what they do not do

Interactive: @claude

With no prompt input the action waits for @claude in an issue or pull request comment, then works in a checkout of the repository and reports in a comment. Setup is /install-github-app from Claude Code, or the app plus one secret (ANTHROPIC_API_KEY, or CLAUDE_CODE_OAUTH_TOKEN for a subscription) by hand.

  • The triggering user must have write access; bots are rejected unless listed in allowed_bots, which keeps two bots from looping.
  • id-token: write is needed for the app's authentication; actions: read lets Claude read CI results on the pull request.
  • Commits made with the default GITHUB_TOKEN do not trigger workflows, which is why the example does not pass one: Claude's pushes then run CI like anyone's.

Claude Code GitHub Actions (official docs)

Automated: the code-review plugin

With a prompt the action runs on the event itself. The review workflow installs the code-review plugin from the Claude Code marketplace and runs its skill with --comment, so findings land as inline comments; the claude_args line is what starts the server that posts them.

  • It skips drafts, closed pull requests, ones it judges trivial, and ones that already carry a Claude comment.
  • On public repositories GitHub withholds secrets from fork pull requests, so the review runs only on branches of the same repository.
  • The hosted Code Review product does the same without a workflow file on Team and Enterprise plans: it finds, verifies and ranks issues, posts a check run named "Claude Code Review", and never approves or blocks a pull request; /code-review runs the same review locally on any plan.

Claude Code GitHub Actions (official docs) · Claude Code Review

Interactive

.github/workflows/claude.yml
# Interactive mode: Claude answers @claude in issue and pull request comments. From the official
# docs (code.claude.com/docs/en/github-actions); the secret is ANTHROPIC_API_KEY or, for a
# subscription, claude_code_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}.
name: Claude Code
on:
  issue_comment:
    types: [created]
  pull_request_review_comment:
    types: [created]
jobs:
  claude:
    if: contains(github.event.comment.body, '@claude')
    runs-on: ubuntu-latest
    timeout-minutes: 30
    permissions:
      contents: write
      pull-requests: write
      issues: write
      id-token: write
      actions: read
    steps:
      - uses: actions/checkout@v6
        with:
          fetch-depth: 1
      - uses: anthropics/claude-code-action@v1
        with:
          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
          claude_args: "--max-turns 30"

Automated review

.github/workflows/claude-review.yml
# Automation mode: the code-review plugin reviews every pull request from a branch in this
# repository and posts inline comments. From the official docs; keep the claude_args line, it is
# what starts the server that posts the comments.
name: Code Review
on:
  pull_request:
    types: [opened, synchronize, ready_for_review, reopened]
jobs:
  review:
    runs-on: ubuntu-latest
    timeout-minutes: 20
    permissions:
      contents: read
      pull-requests: read
      issues: read
      id-token: write
    steps:
      - uses: actions/checkout@v6
        with:
          fetch-depth: 1
      - uses: anthropics/claude-code-action@v1
        with:
          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
          plugin_marketplaces: "https://github.com/anthropics/claude-code.git"
          plugins: "code-review@claude-code-plugins"
          prompt: "/code-review:code-review --comment ${{ github.repository }}/pull/${{ github.event.pull_request.number }}"
          claude_args: '--allowedTools "mcp__github_inline_comment__create_inline_comment"'

Rulesets and owners

The repository's rules close the loop

A ruleset on the default branch turns the checks into a gate and the owners into reviewers. The JSON below is the shape GitHub's API and the import button accept; the rule types and parameters are the documented ones.

What main requires

  • pull_request: one approving review, from a code owner, after the last push, with every thread resolved; stale approvals dismissed on push.
  • required_status_checks with the strict policy: the six jobs, on a branch that is up to date with main.
  • required_signatures and required_linear_history: signed commits, no merge commits.
  • non_fast_forward and deletion: nobody, agent or person, force-pushes or deletes main. bypass_actors is empty on purpose.

GitHub: available rules for rulesets · GitHub REST API: repository rulesets (the JSON shape)

Who reviews what

CODEOWNERS requests reviews automatically; with require_code_owner_review in the ruleset, those reviews are required. The example makes .claude/ owned by the platform team: the agent's own rules are code, and changing them is a reviewed change.

GitHub: about code owners

rulesets/main.json

rulesets/main.json
{
  "name": "main: nothing merges without the gates",
  "target": "branch",
  "enforcement": "active",
  "bypass_actors": [],
  "conditions": { "ref_name": { "include": ["~DEFAULT_BRANCH"], "exclude": [] } },
  "rules": [
    { "type": "deletion" },
    { "type": "non_fast_forward" },
    { "type": "required_signatures" },
    { "type": "required_linear_history" },
    {
      "type": "pull_request",
      "parameters": {
        "required_approving_review_count": 1,
        "dismiss_stale_reviews_on_push": true,
        "require_code_owner_review": true,
        "require_last_push_approval": true,
        "required_review_thread_resolution": true
      }
    },
    {
      "type": "required_status_checks",
      "parameters": {
        "strict_required_status_checks_policy": true,
        "do_not_enforce_on_create": false,
        "required_status_checks": [
          { "context": "lint, unit, property, API" },
          { "context": "mutation score" },
          { "context": "Schemathesis against the OpenAPI schema" },
          { "context": "Playwright" },
          { "context": "promptfoo evals" },
          { "context": "Test Passports" }
        ]
      }
    }
  ]
}

.github/CODEOWNERS

.github/CODEOWNERS
# Code owners are requested for review automatically; the ruleset in rulesets/main.json requires
# their approval before a merge into main.
*                 @acme/platform
src/acme/pricing.py  @acme/payments
infra/            @acme/cloud-security
tests/            @acme/quality
e2e/              @acme/quality
evals/            @acme/quality
.claude/          @acme/platform
.github/          @acme/platform

One pull request

From a 500 to a merged fix, with every gate in the way

  1. 1

    The finding

    Schemathesis, run from the schema alone, reports ST101 Server error and ST103 Undocumented status code on GET /orders/0: 405 generated cases, 3 unique failures, 4.7 seconds (see the example and its video).

  2. 2

    The subagent

    A person asks Claude Code to use the contract-fuzzer subagent. It reruns Schemathesis, writes tests/test_orders_api.py with the two failing cases, and stops: by its definition it does not touch the handler.

  3. 3

    The fix and the hook

    The handler checks order_id not in ORDERS and returns 404. The PostToolUse hook formats the file and runs the fast tests before the agent moves on; the guard would have refused any git push --force along the way.

  4. 4

    The passport

    The new test file gets tests/test_orders_api.passport.yaml: AI-authored, oracle from the contract, checked by a person, with the Schemathesis run as its origin. Without it the Test Passports job fails.

  5. 5

    The pull request

    The template's AI disclosure says who wrote what. The six jobs run; the review workflow posts inline comments; @acme/quality is requested because tests/ changed.

  6. 6

    The merge

    A person reads the scores (mutation unchanged, contract job green, passports B or better), reads the review, approves, and merges with a signed commit. Nightly, the soak and the MCP gates run against the deployment.

src/acme/app.py
@app.get("/orders/{order_id}")
def read_order(order_id: int) -> dict:
    if order_id not in ORDERS:
        raise HTTPException(status_code=404, detail="no such order")
    return ORDERS[order_id]

This site, for real

The page you are reading was built this way

The example project is small so it can be read in one sitting. The repository behind this site is the same shape at full size: one person and Claude Code, a private GitHub repository, and gates that do not care who wrote the change.

Two scheduled jobs, one of them an agent

Every morning at 6:30 Toronto time a scheduled Claude task sweeps the day's AI security news into the Learning Center's data files, translates the new text, runs the tests and commits. It never pushes. At 7:00 and 8:00 the owner's own computer refreshes the headline feeds, rebuilds the site, commits and pushes what is ready. The brief the agent follows is a file in the repository (docs/DAILY.md), edited like code.

The site is a build output, and a test says so

Every page under site/ is generated from YAML. A test rebuilds the whole site and compares it with what is committed, so a hand edit to the HTML, by a person or by an agent, fails the suite. The test center's pages add their own checks: Python examples must parse, every link and fragment must resolve, every fact's source must be a link, and the house style rule against one punctuation mark is enforced by the build, not by a style guide.

Every commit says who wrote it with whom

Commits are authored by the owner and carry a Co-Authored-By trailer for Claude and a link to the session that produced them, so the question the Test Passport asks of tests is already answered for the code: who, with what, from which conversation. The commit that published this page ran 457 tests first.

From this repository's own docs/DAILY.md, tests/ and commit log as of 2026-10-25.

Secrets, permissions, cost

The parts the docs underline

Credentials

Never commit an API key or OAuth token; store it as a GitHub Secret and reference it. For an organization, one organization-level secret with an API key rather than a person's OAuth token, or no stored secret at all through workload identity federation (the action exchanges the workflow's OIDC token).

Permissions

Grant each workflow only what it needs: the review workflow reads contents and pull requests; the interactive one writes them. The app itself carries a wider permission set shared with other Claude features; a custom GitHub App with Contents, Issues and Pull requests covers the action alone.

Cost and runaway runs

--max-turns in claude_args, a workflow timeout-minutes, and a concurrency group with cancel-in-progress cap what one pull request can spend. Specific requests and a concise CLAUDE.md cost fewer turns.

Review before merge

The docs say it in one line: review Claude's changes before merging. The ruleset makes that line a rule.

Claude Code GitHub Actions (official docs)

Watch

The whole shape in about a minute

AI SDLC: Claude Code with GitHub pull requests and Actions 1:13

One repository, one agent writing code, and the gates around it: CLAUDE.md for the rules, hooks for what must always happen, subagents for the tests, Actions for the checks, rulesets so nothing merges without them, and a human at the end. All the videos

Chapters and transcript

Sources

Read on these pages, 2026-10-25

The workflow files marked as taken from the docs are reproduced as published there; the project's other files are ours. Everything in acme-checkout that can run here ran on 2026-10-25: the tests (13 passed), the passport check, the hooks' syntax, and the YAML and JSON parsers.