GitHub integration

Everything so far has been about running Claude Code on your own machine. The GitHub integration moves it into your team's pull request workflow — @claude mentions in issues and PRs, automatic reviews on every new PR, and custom workflows you can tailor to your project's needs. This is the same integration that caught the PII exposure in the Terraform example back in the opening module.

Step 1 — Install the GitHub app

From inside Claude Code, in the repository you want to integrate:

/install-github-app

This command walks you through installing the Claude Code GitHub app, adding the required API key as a repository secret, and opening a pull request that adds two workflow files to .github/workflows/. Merge that PR and the integration is live.

Step 2 — Use the two default actions

Out of the box you get two behaviours:

Mention support: anywhere in an issue or PR, write @claude followed by a task, and Claude Code picks it up. For example, in a PR comment:

@claude please add a test case for the edge case we just discussed.

Claude will read the PR diff, understand the context, implement the change, and push a commit to the branch.

Automatic PR review: every new pull request triggers a review. Claude reads the diff, reasons about it against the repo, and posts review comments on anything it thinks is off.

Step 3 — Customise with workflow YAML

The workflows added by /install-github-app are plain GitHub Actions YAML files in .github/workflows/. You can customise them directly.

Two levers you will reach for most:

Custom instructions: pass project-specific context or directions straight to Claude in the action configuration. Think of this as a CLAUDE.md for the GitHub integration — "this project uses Prisma, always check migrations for destructive operations, prefer TypeScript strict mode patterns."

MCP servers in GitHub Actions: you can wire MCP servers into the workflow by adding mcp_config to the action input. For example, running the Playwright MCP server inside the CI job so Claude can test the UI in a real browser as part of its review.

If you do wire in an MCP server, you will need a step that starts the dev server before Claude runs. That is a standard GitHub Actions step — npm run dev & with a health check — nothing special.

The critical gotcha — MCP permissions in GitHub Actions

This one catches almost everyone, so treat it as a hard rule.

In GitHub Actions, each MCP server tool must be individually listed in the permissions array. There are no blanket permissions.

What that means in practice: locally, you can grant mcp__playwright and Claude can use any Playwright tool. In a GitHub Actions workflow, that does not work. You have to explicitly list each tool you want Claude to be able to call:

allowed_tools:
  - mcp__playwright__browser_navigate
  - mcp__playwright__browser_screenshot
  - mcp__playwright__browser_click
  - mcp__playwright__browser_evaluate

Miss a tool, and Claude will fail to call it mid-review with a permissions error. When that happens, the fix is always the same — look at what Claude tried to do, add that specific tool to allowed_tools, and re-run.

Putting it together

A realistic setup: you install the GitHub app, customise the auto-review workflow with project-specific instructions, wire in the Playwright MCP server so Claude can actually check UI changes in a real browser, and explicitly list each Playwright tool in the workflow's allowed_tools. Every new PR now gets a review that includes visual checks against a running instance of your app.

That is the same pattern that enables the infrastructure-level PII detection demo from the opening module — the more tools Claude has available in the review workflow, the more sophisticated the issues it can catch.