Learning objectives

By the end of this chapter, you will be able to:

1. Explain how Claude Code runs inside GitHub Actions — an event triggers a workflow that runs `anthropics/claude-code-action@v1` on an ephemeral runner, executing Claude Code non-interactively (headless, on the Claude Agent SDK) — and name the two independent credentials involved: the Claude GitHub App for repository access, and an OAuth token or API key stored as a GitHub Actions secret for model authentication.
2. Install and configure the integration by running `/install-github-app` from Claude Code (the documented setup path — `gh` is useful for checking repo/auth state but is not a required prerequisite), install the GitHub App, choose a model credential, and merge the pull request it opens to add an `@claude` assistant workflow under `.github/workflows/`.
3. Trigger Claude on an issue or pull request by mentioning `@claude`, and describe the branch-per-issue model — Claude works on a separate branch under the configurable `claude/` prefix (never `main`), with the default branch template producing names like `claude/issue-<number>-<timestamp>` — plus the default human-in-the-loop safeguard (Claude pushes a branch and a PR link; a human reviews and merges).
4. Diagnose why an autonomous agent can introduce a breaking change without repository context — the third-party-API-contract example and the 'trust-then-verify gap' — and explain why reviewing agent output is non-negotiable.
5. Use `/init` to generate and commit a `CLAUDE.md`, and explain why committed project context measurably improves accuracy for automated runs where no human can course-correct mid-task.
6. Describe the layered safety model for autonomous Claude-on-GitHub — scoped GitHub App permissions, only-write-access-can-trigger, short-lived repo-scoped tokens, prompt-injection caution on untrusted content, a configurable review workflow, and branch protection — and explain how each compensates for the loss of interactive oversight.

Before we start — GitHub Actions, workflows, and two kinds of auth in plain language

Skim this if you already know what GitHub Actions is, how a workflow file is shaped, and the difference between a GitHub App and an API key. If any of that is fuzzy, read it first — every section below leans on these ideas.

GitHub Actions is GitHub's built-in automation platform. You describe a process you want to run automatically — build, test, deploy, or respond to activity in your repo — and GitHub runs it for you on machines it manages. The book calls it "serverless," and that's the right intuition: you never run or patch a server. For each run, GitHub spins up a fresh, temporary virtual machine called a runner, executes your steps, and throws the machine away afterward.

A few terms you'll meet over and over:

• An event is something that happens in your repo — someone comments on an issue, opens a pull request, pushes a commit. You list the events you care about under the on: key. When a matching event happens, the workflow starts. The ones in this chapter: issue_comment (a comment on an issue or PR), issues (an issue opened/assigned), pull_request and pull_request_review (PR activity).
• A workflow is the automated process itself, written as a YAML file committed to your repo under .github/workflows/. Any .yml file in that folder is picked up automatically.
• A job is a group of steps that run together on one runner. A step is one unit of work: either a shell command (run:) or a prebuilt action (uses:).
• An action (lower-case, singular) is a packaged, reusable unit of automation that someone published in a repo. You use one with uses: owner/repo@version — for example uses: actions/checkout@v4 to clone your code, or uses: anthropics/claude-code-action@v1 to run Claude. Inputs go in a with: block underneath. Keep "GitHub Actions" (the platform) and "an action" (one reusable unit) distinct — newcomers conflate them constantly.

Here's the smallest well-formed workflow, so the shape is concrete:

name: CI
on:
  pull_request:
jobs:
  build:
    runs-on: ubuntu-latest          # the runner: a fresh Ubuntu VM
    steps:
      - uses: actions/checkout@v4    # a prebuilt action: clones the repo
      - run: echo "Hello from the runner"   # a shell command

Secrets. A workflow often needs a token or API key. You never write those in the YAML — you store them as encrypted GitHub Actions secrets in the repo's settings and reference them as ${{ secrets.NAME }}. GitHub injects the value at run time and masks it in the logs. (One security property worth knowing: secrets are not passed to workflows triggered by a pull request from a fork — only the limited, read-only GITHUB_TOKEN is.)

Two kinds of authentication — keep them separate. The Claude integration involves two independent credentials, and blurring them is the single most common source of confusion:

1. The Claude GitHub App authenticates Claude to GitHub itself — reading issues and PRs, posting comments, pushing commits. A GitHub App is an installable integration with fine-grained, per-repository permissions you grant at install time, authenticating with short-lived tokens. (This is different from a personal access token, which acts as you with your full access, and from an OAuth token, which authorizes an app to act on your behalf. GitHub recommends Apps for integrations precisely because their permissions are scoped and their tokens are short-lived.)
2. Model authentication is a separate credential that lets Claude Code call the Anthropic model from inside the runner — either a long-lived Anthropic OAuth token (tied to a Claude subscription) or an API key. This one lives as a GitHub Actions secret. It has nothing to do with the GitHub App's permissions.

Finally, two GitHub objects you mostly already know: an issue is a tracked work item (a bug, a task, a request); a pull request (PR) proposes merging one branch's changes into another and opens a surface for review, comments, and automated checks before anything merges.

Why this chapter matters

Up to now, Claude Code has lived on your laptop. Chapter 1 was the theory of context engineering. Chapter 2 was the startup pass — CLAUDE.md, permissions, plan mode. Chapter 3 was the daily operating surface. Chapter 4 wired Claude into the rest of your stack with MCP and plugins. In every one of those, you were sitting there — watching each step, approving each permission, course-correcting the moment something looked off.

Chapter 5 is the first time Claude Code works without you in the room. You tag @claude on a GitHub issue and walk away; a GitHub Actions runner spins up, Claude reads the repo, makes changes on a branch, and opens a pull request — while you're at lunch. This is genuinely useful: Anthropic's own Product Design team automated pull-request comments this way, with Claude handling formatting fixes and test refactors on its own. It's also where the stakes change. When there's no human to interrupt mid-task, the safety that was "you, watching" has to move somewhere else: into the context you give the agent up front (a committed CLAUDE.md), the permissions you scope, and the review gate you put before merge.

The chapter teaches both halves honestly. It shows the integration working — and then it shows it failing, on purpose: Claude renames a variable that turns out to be part of a third-party API contract, silently breaking the integration. That failure is the whole point. By the end you'll know how to wire Claude into GitHub, and why "looks done" is never the same as "is correct" when an agent runs unattended.

How to read this chapter. Each numbered section ends with an > Analogy — … box that restates the idea in plain language. Lean on them or skim them as you like.

Lesson

1. From your laptop to the repo — what changes when Claude runs unattended

Interactive Claude Code and automated Claude Code are the same agent doing the same kind of work. The difference is everything around it.

That last row is the heart of it. In an interactive session, if Claude starts down the wrong path you stop it. In headless mode there is no one to ask — Anthropic's own docs note that when a headless run hits a permission boundary, the process simply terminates rather than silently pushing past it. So the design shifts: you stop relying on live oversight and start relying on what you told the agent before it started and what you check after it finishes.

This is why the book opens the chapter with GitHub and not, say, a fancier prompt. The integration is the easy part — a few install steps. The discipline is the hard part, and it's the same discipline from Chapter 1, now load-bearing because the human safety valve is gone.

Analogy — the contractor who works after hours Hiring a contractor who works while you watch is one thing — you catch a wrong cut before the second one. Giving them a key so they work overnight while you sleep is another. You can't correct them mid-job, so everything rides on two things: the written instructions you left taped to the wall, and the walk-through you do in the morning before you pay. Automating Claude on GitHub is handing over the key.

2. The architecture — Claude Code, GitHub Actions, and the Agent SDK

Here's what actually happens, mechanically, when you tag @claude on an issue.

1. Your comment is an event (issue_comment, type created).
2. The event matches the on: block of the workflow file .github/workflows/claude.yml, so GitHub starts the workflow.
3. The workflow's one job spins up an ephemeral Ubuntu runner and runs its steps. The key step is uses: anthropics/claude-code-action@v1 — the official Anthropic action.
4. That action runs Claude Code non-interactively — headless mode, the same claude -p-style execution you'd use in any CI script. Under the hood the action is built on the Claude Agent SDK (the SDK was previously called the "Claude Code SDK"; it's the programmatic way to run the same agent that powers the CLI).
5. To do its work, Claude needs two credentials, and they are independent:

• the GitHub App token, which lets it read the issue, push a branch, and comment — scoped to this one repo;
• the model credential (OAuth token or API key), read from a GitHub Actions secret, which lets it call the model.

1. Claude does the task on a new branch, then surfaces a pull request. In the action's default configuration, it does not merge anything — a human reviews and merges.

A couple of details the book's example simplifies, worth getting right because they're what you'll actually see today:

• The action is anthropics/claude-code-action@v1, not @beta. The action went to a stable v1 in 2025; the book's @beta tag is from an earlier build. There's now a single unified action that auto-detects whether it's responding to an @claude mention or running an automation, so the old mode: "tag" / mode: "agent" inputs are gone.
• The example workflows listen on more than one event. The book shows only issue_comment; the action's examples/claude.yml currently also listens on pull_request_review_comment, issues, and pull_request_review, so Claude can be summoned from review threads and new issues too. (The docs' inline "basic workflow" shows a shorter two-event version, and the examples directory has several variants — treat any single file as representative, not canonical, and check the current examples before you copy one.)

Analogy — the dispatch desk Think of GitHub Actions as a dispatch desk. An event is a call coming in. The workflow file is the standing instruction sheet that says "for this kind of call, send this crew." The runner is the truck that gets dispatched — fresh each time, returned to the depot after. The action is the specialist riding in the truck. And the specialist carries two badges: one that opens the building (GitHub App), one that bills the work (model credential). Lose track of which badge is which and you'll spend an afternoon debugging the wrong one.

3. Installing and configuring the integration

The setup is driven by one command. From a Claude Code session opened inside a directory that is a Git repository connected to GitHub (this matters — the integration only works in a valid GitHub repo, and you need admin access to install the App and add secrets):

/install-github-app

The book reaches this via typing /git first; in current builds /install-github-app is a standalone command you can invoke directly. It walks you through the following.

Step 1 — (Optional) the GitHub CLI. The book walks through installing and authenticating the gh CLI first, as a prerequisite. It's genuinely handy — gh repo view and gh auth status are the quickest way to confirm you're in a GitHub-connected repo and signed in — but the current official docs do not list gh as a required prerequisite for /install-github-app. The documented setup path is simply running /install-github-app from Claude Code in a repo you administer; the command itself walks you through the GitHub App install and the secret. If you want gh anyway (the command varies by OS — the book shows macOS Homebrew; on Windows use winget install --id GitHub.cli, on Linux follow https://cli.github.com/):

brew install gh        # macOS; see cli.github.com for Windows/Linux
gh --help              # verify it's on your PATH
gh auth login          # authenticate

During gh auth login, choose HTTPS as the connection method and log in through the browser with the one-time code. With two-factor enabled, approve with your second factor. Once that completes, your gh session is authenticated — useful for checking repo state, though /install-github-app does not depend on it.

Step 2 — Install the Claude GitHub App. Back in Claude Code, press Enter to continue and you're redirected to a GitHub page to install the Claude GitHub App (https://github.com/apps/claude). You choose which repositories it can touch; it requests read & write on Contents, Issues, and Pull requests — nothing broader. Click Install, return to the terminal, press Enter again.

Step 3 — The workflow it sets up. The book describes the installer presenting a choice of two templates — "Tag Claude" (respond to @claude mentions) and "Claude Code Review" (auto-review new PRs). The current docs describe /install-github-app more simply: it sets up the GitHub App plus the required secret, and adds an @claude assistant workflow (claude.yml) that responds to mentions in issues and PR comments. **Automated PR review is a separate workflow you add yourself** — the action's examples directory ships ready-to-copy review workflows such as pr-review-comprehensive.yml, pr-review-filtered-paths.yml, and manual-code-analysis.yml. So treat "two templates named Tag Claude / Claude Code Review" as the book's description of an earlier installer; what you'll reliably get today is the @claude assistant workflow, and you copy in whatever review workflow you want. (Anthropic also offers a separate managed Code Review product — see §7 — which is a different thing entirely.)

Step 4 — Choose a model credential. Someone has to pay for the tokens Claude consumes. Two options:

• A long-lived OAuth token tied to a Claude subscription (Pro, Max, Team, or Enterprise). Generate it with claude setup-token — it prints a token (format sk-ant-oat01-…, valid about a year) that you store as the secret CLAUDE_CODE_OAUTH_TOKEN. Good for small-to-medium usage inside a subscription. (Billing caveat, as of writing — verify the current terms in the authentication docs: per Anthropic, starting June 15, 2026, Agent SDK and claude -p usage on subscription plans draws from a new monthly Agent SDK credit, separate from your interactive usage limits. The GitHub Action runs Claude headlessly via the Agent SDK, so a subscription token used in CI is subject to this.)
• An Anthropic API key, stored as the secret ANTHROPIC_API_KEY. Typical for large-scale or high-frequency workflows that would exceed subscription limits.

(Beyond these two, the action also supports Amazon Bedrock, Google Vertex AI, and Microsoft Foundry for teams whose models are hosted there, plus Workload Identity Federation so there's no static key to store. The book covers only the first two; the others are there if your org needs them.)

Whichever you pick, the credential is stored as a GitHub Actions secret, set up automatically during configuration. Nothing sensitive lands in the workflow file.

Step 5 — Merge the setup PR. The install flow fetches your repo info and opens a pull request that adds a workflow under .github/workflows/ — the @claude assistant workflow claude.yml. (The book shows two files, claude.YAML and claude-code-review.YAML; the uppercase extension is an OCR artifact — real workflow files are lowercase .yml — and, per Step 3, a dedicated review workflow is something you copy in from the examples rather than a guaranteed installer output. Review exactly what the PR contains before merging.) The new workflow runs as a check on that very PR — once it passes, merge. Your repo now has a .github/workflows/ directory it didn't have before.

Here is a representative claude.yml — close to the action's current examples/claude.yml — so you know the shape of what you're merging. The official examples can change between releases, so verify against the live examples directory rather than treating this as canonical:

name: Claude Code
on:
  issue_comment:
    types: [created]
  pull_request_review_comment:
    types: [created]
  issues:
    types: [opened, assigned]
  pull_request_review:
    types: [submitted]

jobs:
  claude:
    # only run when the comment/issue/review actually mentions @claude
    if: contains(github.event.comment.body, '@claude') || contains(github.event.issue.body, '@claude')
    runs-on: ubuntu-latest
    permissions:
      contents: write
      pull-requests: write
      issues: write
      id-token: write
      actions: read          # lets Claude read CI results on the PR
    steps:
      - uses: actions/checkout@v4
      - uses: anthropics/claude-code-action@v1
        with:
          claude_code_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}
          # or: anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}

Notice the permissions: block — it's least-privilege: the job can write Contents, Issues, and PRs, but nothing else. And notice the token is a ${{ secrets.… }} reference, never the value. The book's closing note for this section is right and worth keeping: the integration can be customized further — selecting the model, restricting which tools Claude may use, and more. We'll get to that in §7.

Analogy — onboarding a new hire Setup is the first day of a new hire. The gh login is them proving who they are at the front desk. Installing the GitHub App is facilities granting them a building badge scoped to the floors they need. Choosing the model credential is payroll setting up how their work gets billed. And the secret store is the locked drawer where the badge and the payroll code live — never written on a sticky note left on the monitor. Two credentials, two purposes; don't hand them the CFO's keys to read one email.

4. Tagging @claude to resolve an issue — and why it broke

With the integration installed, summoning Claude is one comment. The book's worked example uses a real issue on the IceBreaker project: a user asked to rename a variable from linkedin_username to linkedin_url, because the variable actually holds a URL. On the issue, someone comments:

@claude, can you fix this

The mention fires the workflow (the run even gets a human-readable name like "small rename"). You can open the Actions tab and watch the raw logs stream — but they're mostly JSON tool calls and outputs, great for deep debugging and miserable for following along. Better to watch the issue itself, where Claude posts a to-do list that updates as it works.

The very first thing Claude does is look for a CLAUDE.md in the repo — the project-context file from Chapters 1–3. Its purpose is exactly what you'd expect: tell Claude the tech stack, the structure, the conventions, the things you can't infer from the code alone. This is context engineering, the discipline from Chapter 1, showing up at the moment it matters most.

Spoiler: this repo has no CLAUDE.md. That's deliberate. Claude proceeds anyway, finishes its to-do list, works on a branch, and surfaces a pull request. In the action's default configuration it commits the change to a branch and hands back a PR-creation link rather than opening or merging the PR itself — keeping a human in the loop. The PR description reads reasonably. And then you look at the actual diff.

Claude renamed the variable — including in a payload that gets sent to a third-party API. The external service expects the request body to use a specific set of key names. linkedin_username was one of them. Rename it to linkedin_url and the request no longer matches the contract the external endpoint enforces, so the call fails. The change looks like a clean readability fix. It's a production break.

This is the chapter's most important lesson, and Anthropic's own best-practices guidance names the failure mode precisely: the trust-then-verify gap — "Claude produces a plausible-looking implementation that doesn't handle edge cases." The remedy in their words: "Always provide verification. If you can't verify it, don't ship it." "Looks done" is the only signal an unattended agent has; without an actual check — a human review, or better, a test that exercises the contract — that's all you get. The book states the principle plainly: review any change carefully rather than accepting it blindly, and this applies to every agentic workflow, not just this one.

Analogy — the eager intern and the load-bearing label A sharp new intern is told "that column name is ugly, clean it up." They rename cust_id to customer_id everywhere — tidy, readable, and they did exactly what was asked. What nobody told them is that a partner company's nightly import matches on the literal string cust_id. Monday morning the import is broken. The intern wasn't careless; they were uninformed. The fix isn't a smarter intern — it's telling them, before they start, which labels are load-bearing.

5. The branch-per-issue model — control, and why it scales

One detail in that failure is quietly reassuring: Claude never touched main. It does its work on a separate branch it creates automatically, under the action's claude/ branch prefix — never the default branch. The exact name is configurable: the action's default branch-name template produces names like claude/issue-<number>-<timestamp> (e.g. claude/issue-950-20250711_082715), but both the prefix and the template are configurable inputs, so don't hard-code an exact suffix into your tooling. (The book writes the older claude/issue/<issue-number> slash form; the part you can rely on is simply a separate branch under claude/, not main.) Because the change lives on its own branch behind a pull request, you decide whether to review, modify, or merge it. The broken rename never had a path to production that didn't go through a human.

This branching strategy isn't just a safety convenience — it's the foundation for scaling agentic work. Because each task gets its own isolated branch, you can run multiple Claude instances in parallel, each on its own branch, without them stepping on each other. That idea grows into Git worktrees, which the book covers later. For now, the takeaway is: one issue, one branch, one PR, one human decision.

The security model around triggering reinforces this:

• Only users with write access to the repo can trigger Claude. A drive-by comment from a random account won't fire the workflow. Bots are blocked by default.
• The runner gets a short-lived token scoped to the single repo — no cross-repo reach, and it expires.
• Be careful with untrusted content. When you tag Claude on an issue or PR opened by an external contributor, that text can contain hidden instructions — invisible characters or HTML comments crafted to redirect the agent (a prompt-injection attempt). Anthropic's action security docs explicitly recommend reviewing the raw content of anything from outside contributors before letting Claude act on it.

Analogy — everyone gets a photocopy of the blueprints A well-run architecture firm never lets anyone draw on the master blueprints. Each person works on a photocopy; changes only reach the master after the lead reviews and signs off. Claude's branch is the photocopy. main is the master. The rename disaster scribbled all over a photocopy — annoying, instantly discardable, and it never touched the original.

6. Adding repository context with CLAUDE.md — the fix

The hypothesis is now obvious: Claude broke the contract because it didn't know the contract existed. Let's give it the context and re-run.

Step 1 — Generate the context file. Open the project locally (in your editor or IDE — the book uses Cursor; any works) and, in Claude Code, run:

/init

/init scans the repository and writes a CLAUDE.md capturing the tech stack, structure, and conventions. During the scan, Claude asks permission to run commands like listing files; you allow them, and the approvals are written to a local settings file (.claude/settings.local.json) so they persist for the session — fine-grained control over what Claude may do. When the scan finishes, Claude writes the file.

Step 2 — Review and improve it. Open the generated CLAUDE.md and read it. The auto-generated summary is a good start — but the single most valuable thing you can add is exactly the fact that would have prevented the break: a note that the LinkedIn variable is part of a third-party API payload whose key names must not change. Anthropic's best-practices guide is explicit that CLAUDE.md is for "persistent context [Claude] can't infer from code alone" — and lists "common gotchas or non-obvious behaviors" as a thing to put there. "This name is load-bearing for an external contract" is precisely such a gotcha.

Step 3 — Commit it. Ask Claude to commit CLAUDE.md; review the commit message; accept. Now it's versioned, shared with the team, and — critically — available to Claude when it runs inside GitHub Actions. That last part is the whole game: the automated run on the runner reads the committed CLAUDE.md just like your local session does. Anthropic's GitHub Actions docs put it directly: "Claude respects your CLAUDE.md guidelines and existing code patterns."

Step 4 — Re-tag Claude. Back on the issue, mention Claude again (the book adds a small hint pointing at the right function — it admits this biases the experiment slightly, but the effect of context still shows):

@claude, can you please address this issue?
Please notice that you need to edit the function ice_break_with

The workflow fires. This time Claude updates the variable consistently in the function definition and at the call site, while preserving the external API payload key — the rename is applied where it's safe and avoided where it isn't. The logic is correct, the contract intact. A pull request titled "Renamed linkedin_username to linkedin_url" now accurately describes a change that's actually right.

Why does this matter more for automated runs than interactive ones? Because in an interactive session you're the missing context — you'd have caught it live and said "no, don't touch that key." In an unattended run there's no you. The committed CLAUDE.md is the substitute for the over-the-shoulder correction. Two honest caveats keep this from becoming magical thinking: CLAUDE.md is advisory, not a hard guarantee — for a rule you must enforce, use a hook or a required test, not a sentence in a doc; and keep it short — Anthropic warns that a bloated CLAUDE.md causes Claude to ignore your actual instructions.

Analogy — the runbook on the wall Back to the after-hours contractor. The reason the morning went badly wasn't the contractor — it's that nobody left a runbook. The fix is a single sheet taped by the door: "Load-bearing wall, do not move. Gas line behind panel C. The blue valve is the supplier's, never touch it." /init drafts that sheet; you add the one line that actually matters; committing it tapes it to the wall so it's there every night, for every contractor, including the one who works while you sleep.

7. Configuring the review workflow — what "fully configurable" really means

Beyond the @claude assistant workflow, you can add an automated PR-review workflow that runs when a pull request is opened — no one has to tag it. The book installs this as a second template ("Claude Code Review"); today you add it yourself by copying one of the action's review examples (e.g. pr-review-comprehensive.yml) into .github/workflows/. In the corrected example, the moment the good PR opens, that review workflow fires: Claude reads the diff and posts a structured review — a checklist of what it examined and what it found. Here it approves, finding no functional issues.

The book notes this review system is "fully configurable," and that's worth making concrete, because it's how you turn a generic reviewer into one that enforces your standards. The v1 action exposes two main knobs: a prompt (plain text, or the name of a skill to run) and claude_args — a pass-through for any Claude Code CLI argument. Through claude_args you can:

• Run your tests and linters as part of the review — --allowedTools "Bash(npm run test:*),Bash(npm run lint:*)" lets Claude actually execute them. A real test that exercised the LinkedIn payload would have caught the §4 break mechanically, before any human looked.
• Pin the model and bound the work — --model …, --max-turns 10.
• Inject review criteria — --system-prompt "Flag any change to an external API payload. Ensure new code has tests."

There's a deeper reason a separate automated reviewer helps, beyond convenience. Anthropic's best practices point out that "a fresh context improves code review since Claude won't be biased toward code it just wrote." The review workflow runs as its own job with its own clean context — it sees only the diff and your criteria, not the reasoning that produced the change. That independence is exactly why a second pass catches what the first missed.

Two things to keep distinct so you're not surprised later:

• The review workflow you self-host via the action (a pr-review-*.yml you add yourself) is not the same as Anthropic's managed Code Review product (a research-preview feature for Team/Enterprise plans, run on Anthropic's infrastructure, configured in the Claude admin settings, billed per review — averaging roughly $15–25 each). Both read your CLAUDE.md to shape what they flag — the managed one even works bidirectionally, flagging when a PR makes a CLAUDE.md statement outdated — but they're different things. This chapter is about the self-hosted GitHub Action.
• The strongest enforcement doesn't live in Claude at all: GitHub branch-protection rules (require a passing check, require a human review, restrict who can push to main) are the deterministic backstop. Claude's review is advice; branch protection is the gate.

Analogy — the QA bench with its own checklist A good factory doesn't let the person who built a part also be the one who passes it. The part goes to a QA bench staffed by someone who didn't build it, working from a written checklist, with calipers that actually measure. The automated review workflow is the QA bench: fresh eyes (clean context), your checklist (--system-prompt, CLAUDE.md), and real instruments (tests and linters run via claude_args). And the locked gate past the bench — the part can't ship until QA signs and the gate opens — is branch protection.

The whole chapter in one image — the contractor with a key to the shop

Analogy — pedagogical summary, drawing on all seven sections

You've decided to give a skilled contractor a key so they can work in your shop after hours, on jobs you'll review in the morning. That decision is this whole chapter.

Wiring up the access is the install. They prove who they are at the front desk (gh auth login). Facilities issues a badge scoped to just the rooms they need (the GitHub App, with read/write on Contents, Issues, PRs — nothing more). Payroll sets up billing for their hours (the model credential), and both the badge and the billing code go in a locked drawer, never on a sticky note (GitHub Actions secrets). The dispatch desk gets a standing instruction sheet: for this kind of call, send this contractor (the claude.yml workflow, triggered by an @claude mention).

The first overnight job goes wrong — not because the contractor is bad, but because the shop had no rules posted. Asked to "clean up that label," they rename a part that a supplier matches on, and the supplier's delivery breaks (the third-party API contract). The damage is contained to one thing only: they worked on a photocopy of the blueprints, never the master (the claude/issue-… branch, never main), so nothing shipped — you caught it at the morning walk-through (the PR review). The lesson lands hard: looks done is not is correct when nobody's watching the work happen.

The fix is a runbook on the wall. You tape up a single sheet — the blue valve is the supplier's, never touch it (/init drafts the CLAUDE.md, you add the one load-bearing line, you commit it so it's there every night for every contractor). The same job, re-run with the runbook posted, comes out right.

And you keep a QA bench by the door. A second person who didn't do the work checks every job against a written checklist with real instruments (the review workflow — fresh context, your criteria, tests and linters run for real), and the part can't leave until QA signs and the gate unlocks (branch protection).

That's the chapter. The integration is a few commands. The discipline — context up front, scoped access, a review gate — is what makes handing over the key a good idea instead of a bad one.

Activity — Write the CLAUDE.md lines that would stop a 2 a.m. mistake

Ten minutes, individual, no setup required. Pick a real repository you work in (or one you know well).

1. List three to five facts about this repo that an autonomous agent would get wrong if nobody told it — the load-bearing labels, the things that look safe to change but aren't. Examples to prime the pump: a field name that's part of an external API or DB contract; a generated file that must not be hand-edited; a "temporary" hack that other code depends on; a naming pattern that a downstream system matches on; a directory that looks like dead code but is loaded dynamically.
2. For each, write the single CLAUDE.md line that would prevent the mistake. Aim for one crisp sentence each — "events.user_id is sent verbatim to the billing provider; never rename or reshape it."
3. For the worst one — the fact whose violation would cause real damage — decide whether a sentence in CLAUDE.md is actually enough, or whether it needs hard enforcement (a required test, a pre-merge check, a hook). Note which, and why. (CLAUDE.md is advisory; some things need a gate.)
4. Count your lines. If your draft CLAUDE.md is over ~15 lines, cut it to the most important 8–10. Bloat gets ignored.

Keep the result — it's a real artifact you can commit, and it's exactly the kind of context that turns the §4 break into the §6 success.

Stretch task (enrichment)

Sketch (don't build) the PR-review workflow you'd want for that repo (start from one of the action's pr-review-*.yml examples and name your copy whatever you like — pr-review.yml, say). Write the one --system-prompt sentence that names the thing your reviewer must never wave through, and the one --allowedTools "Bash(…)" entry that would let the reviewer mechanically verify it (a test, a lint, a schema check) instead of just eyeballing it. Two lines. They're the difference between a reviewer that hopes and one that checks.

Practical exercise — Drive the autonomous loop and prove that context fixes it

~35–45 minutes. Hands-on. Two tracks. Track A wires the real GitHub integration (needs admin access to a GitHub repo you own, and a Claude subscription or API credit; the gh CLI is handy for checking state but isn't required). Track B reproduces the chapter's central finding entirely locally with no GitHub account and no admin — everyone can do this one. If you can't do Track A today, do Track B; it teaches the load-bearing lesson (context engineering for unattended runs) without the setup cost.

Pick a throwaway sandbox repo for either track — nothing here touches the training repo or anything you care about.

Track B — the no-GitHub lab (reproduce the break, then fix it)

You'll simulate exactly what the GitHub Action does — run Claude Code non-interactively (headless) on a task, with no human watching — first without context, then with it.

Setup (5 min). Create a tiny repo with a file that has a load-bearing variable name, mirroring the chapter:

mkdir -p ~/cct-ch5-lab && cd ~/cct-ch5-lab
git init -q
cat > linkedin.py <<'PY'
import requests

def ice_break_with(linkedin_username: str):
    # linkedin_username is sent VERBATIM to the third-party enrichment API.
    # The external service matches on the exact key "linkedin_username".
    payload = {"linkedin_username": linkedin_username}
    return requests.post("https://api.example-enrich.com/v1/lookup", json=payload)
PY
cat > issue.md <<'MD'
# Issue: rename linkedin_username to linkedin_url
The variable actually holds a URL. Rename it for readability.
MD
git add . && git commit -q -m "init"

Step 1 — Run the task headless, with no CLAUDE.md (5 min). This is the same non-interactive execution mode the GitHub Action uses. From ~/cct-ch5-lab:

claude -p "Read issue.md and linkedin.py, then apply the requested rename. Edit the files." --allowedTools "Read,Edit"

Expected outcome: Claude renames linkedin_username → linkedin_url. Inspect the diff — git diff. There's a good chance it renamed the payload key "linkedin_username" too (or at least didn't flag that doing so is dangerous). That's the §4 break: a plausible-looking change that violates the external contract. Note what it did.

git stash       # set the attempt aside so you can compare

Step 2 — Add the one load-bearing line of context (5 min). Create CLAUDE.md:

# Project context

## Gotchas — read before editing
- `linkedin.py` builds a JSON payload sent to a third-party enrichment API.
  The external service matches on the **exact** key string `"linkedin_username"`.
  You may rename the local Python variable, but you must NOT change that
  payload key — doing so breaks the external API contract.

git add CLAUDE.md && git commit -q -m "add CLAUDE.md with the API-contract gotcha"

Step 3 — Re-run the identical headless task (5 min):

claude -p "Read issue.md and linkedin.py, then apply the requested rename. Edit the files." --allowedTools "Read,Edit"

Expected outcome: this time Claude renames the local variable consistently (definition and call site) but leaves the payload key "linkedin_username" intact — exactly the §6 correct change. git diff should show the dict key unchanged. The only thing that changed between the broken run and the correct run was the committed context.

Step 4 — Prove the point with a real check (5 min). Context is advisory; a test is a gate. Add one and see it catch the bad version:

cat > test_contract.py <<'PY'
import inspect, linkedin
def test_payload_key_is_preserved():
    src = inspect.getsource(linkedin.ice_break_with)
    assert '"linkedin_username"' in src, "external API payload key must not change"
PY
python -m pytest -q       # passes against the good change
git stash pop             # bring back the broken attempt…
python -m pytest -q       # …and watch the same test FAIL

Reflection: in a real GitHub Action, Step 4's test is what you'd wire into your PR-review workflow (a pr-review-*.yml copied from the action's examples) via --allowedTools "Bash(python -m pytest:*)". The human-in-the-loop review is one backstop; a mechanical check the agent runs is a better one. Which would you trust at 2 a.m.?

Track A — the real GitHub integration (if you have a repo + admin + model credit)

1. Pick a repo you own, clone it, and open Claude Code inside it. Confirm it's a real GitHub repo (gh repo view, or just check it has a GitHub remote — gh is optional).
2. (Optional) sign in to gh if you want it for checking state: gh auth login (HTTPS, browser). Not required for the next step.
3. Run /install-github-app in Claude Code. Install the Claude GitHub App on just this repo, and follow the prompts to add the model-credential secret and the @claude assistant workflow (claude.yml). If you want automated PR review too, copy a review example (e.g. pr-review-comprehensive.yml) from the action's examples directory into .github/workflows/ separately.
4. Provide a model credential: run claude setup-token for an OAuth token (or use an API key) and let the installer store it as the GitHub Actions secret. Review and merge the setup PR that adds .github/workflows/.
5. Open an issue asking for a small, safe change (e.g., "add a docstring to function X"). Comment @claude, can you do this?. Watch the Action run in the Actions tab, then watch the to-do list on the issue.
6. Review the branch and PR Claude produces. Confirm the branch name follows claude/issue-… and that main is untouched. Do not auto-merge — read the diff first.
7. Add and commit a CLAUDE.md (use /init, then add one project-specific "gotcha" line). Open a second, slightly riskier issue and re-run. Compare how the context changes Claude's output.

Success checklist

• [ ] (Track B) You have a git stash'd "broken" attempt and a committed "correct" attempt, and git diff shows the payload key changed in one and preserved in the other.
• [ ] (Track B) The same pytest check passes on the good change and fails on the broken one.
• [ ] (Track B) You ran the task with claude -p (headless) — the same non-interactive mode the GitHub Action uses — at least twice.
• [ ] (Track A) The integration installed; .github/workflows/claude.yml exists; the credential is a secret, not inline.
• [ ] (Track A) You triggered Claude with @claude, watched the Action run, and reviewed a claude/issue-… branch without merging blindly.
• [ ] (Either) You can state, in one sentence, why committed context matters more for unattended runs than interactive ones.

Common pitfalls - /install-github-app errors out. Almost always because Claude Code was launched from a directory that isn't a GitHub-connected Git repo, or you lack admin on the repo. Re-open Claude in a valid repo you administer. - Mention not triggering. It must be @claude, not /claude, and only users with write access can trigger it — a comment from an account without write access is ignored by design. - The Action runs but can't authenticate the model. The secret name must match what the workflow references (CLAUDE_CODE_OAUTH_TOKEN or ANTHROPIC_API_KEY). A token from claude setup-token is the OAuth one. - (Track B) claude -p asks for permission anyway. Pass --allowedTools "Read,Edit" (and Bash(...) patterns for Step 4) so the headless run has what it needs; headless mode can't pop an interactive prompt, so an un-allowed tool just stops the run. - Expecting Claude to merge for you. By default it doesn't — it pushes a branch and a PR link. That's the human-in-the-loop safeguard, not a bug.

Knowledge check — try the quiz

Once you've read the lesson and worked the lab, take the chapter quiz from the navigation bar. Six questions: five grounded in the book chapter, one synthesis question that ties the integration to the layered safety model for autonomous agents. Retake it until you're confident.

Further reading & enrichment sources

• Anthropic docs — "Claude Code GitHub Actions" (https://code.claude.com/docs/en/github-actions). The canonical install flow, the claude.yml template and its events, the prompt/claude_args configuration model, and the "Security considerations" checklist (review before merge; least-privilege permissions).
• anthropics/claude-code-action — repo, examples, and security doc (https://github.com/anthropics/claude-code-action, …/tree/main/examples, …/blob/main/docs/security.md). The @v1 action, ready-to-copy example workflows, the "only write-access can trigger" rule, the "Claude does not auto-create PRs by default" guarantee, and the prompt-injection caution on untrusted content.
• Anthropic docs — "Authentication" (https://code.claude.com/docs/en/authentication). How claude setup-token generates the long-lived CLAUDE_CODE_OAUTH_TOKEN, the full list of model-auth paths (subscription token, API key, Bedrock, Vertex, Microsoft Foundry, WIF), and the dated note that — as of writing — starting June 15, 2026 Agent SDK / claude -p usage on subscription plans draws from a separate monthly Agent SDK credit. Verify current billing terms here before relying on a subscription token in CI.
• Anthropic docs — "Claude Code best practices" (https://code.claude.com/docs/en/best-practices). Source of the trust-then-verify gap, "if you can't verify it, don't ship it," the "give Claude a way to verify its work" guidance, the fresh-context reviewer argument, and the CLAUDE.md-as-persistent-context framing used in §4–§7.
• Anthropic docs — "Headless mode" and "Claude Agent SDK overview" (https://code.claude.com/docs/en/headless, …/agent-sdk/overview). Why claude -p is the non-interactive entry point the GitHub Action is built on, and what changes when there's no human to answer a permission prompt.
• Anthropic blog — "How Anthropic teams use Claude Code" (https://claude.com/blog/how-anthropic-teams-use-claude-code). The Product Design team's automated PR-comment workflow via GitHub Actions, and the Security Engineering team's periodic-human-checkpoint discipline.
• GitHub docs — workflows, events, secrets, and GitHub Apps vs OAuth apps (https://docs.github.com/en/actions). The GitHub-side concepts behind the newcomer preface.