GitHub Actions and Automated Code Review

claude-code-action is a GitHub Action built on top of the Claude Agent SDK. Simply put: the same agentic loop engine that runs in your terminal now executes directly inside a GitHub CI runner. The agent receives context from the repository, reads files, writes code, and interacts with the GitHub API — all on standard ubuntu-latest runners, without touching your own infrastructure.

It is important to distinguish two modes from the outset, as they are often confused:

• Interactive mode — the agent responds to @claude mentions in PR or issue comments. This is an on-demand trigger: someone writes a message, the agent reads the context and completes the task.
• Automated mode — the agent runs without a comment trigger: on a schedule, when a PR is opened, or on any GitHub event. Here you pass instructions via the prompt parameter directly in the YAML file.

There is also a third option — Code Review, a managed service hosted on Anthropic's infrastructure. We will cover it separately at the end.

Architecture: What Happens Behind the Scenes

When someone writes @claude in a PR comment, here is what happens:

sequenceDiagram
    actor Dev as Developer
    participant GH as GitHub
    participant App as Claude GitHub App
    participant Runner as GitHub Runner
    participant Agent as Agent (Agent SDK)
    participant API as Anthropic API

    Dev->>GH: Comment «@claude fix the bug»
    GH->>App: Webhook: issue_comment event
    App->>Runner: Trigger workflow
    Runner->>Runner: actions/checkout (opt.)
    Runner->>Agent: anthropics/claude-code-action@v1
    Agent->>GH: Reads PR context, diffs, files
    Agent->>API: Agent loop (plan → tool calls)
    loop Tools
        Agent->>Runner: Read / Edit / Bash
        Agent->>GH: GitHub API (get_pr_files etc.)
    end
    Agent->>GH: Creates commit / leaves comment
    GH->>Dev: Result notification

1. The GitHub App (github.com/apps/claude) receives a webhook event

2. A workflow from .github/workflows/ is triggered

3. The anthropics/claude-code-action@v1 action starts the agentic loop

4. The agent reads context: diffs, files, comment history

5. It executes tools (Read/Edit/Bash/GitHub API)

6. It posts the result as a comment or creates a PR/commit

The key difference from local execution: the agent runs on a GitHub runner (an isolated virtual machine), has access to the repository via actions/checkout, and communicates with the GitHub API through a GitHub App token.

Quick Setup: /install-github-app

For most repositories, the simplest path is to run the following in your terminal:

claudeproject:~$ claude
/install-github-app

The command walks you through the steps: installs the GitHub App (https://github.com/apps/claude) into the repository, adds the ANTHROPIC_API_KEY secret, and creates the .github/workflows/claude.yml file.

Limitation: /install-github-app only works if you are using the Anthropic API directly. For Amazon Bedrock or Google Vertex AI, manual setup is required (see below).

Manual Setup

If auto-installation is not suitable or you need full control:

Step 1. Install the GitHub App: https://github.com/apps/claude. Required repository permissions: Contents (read & write), Issues (read & write), Pull requests (read & write).

Step 2. Add the ANTHROPIC_API_KEY secret in Settings → Secrets and variables → Actions.

Step 3. Create the .github/workflows/claude.yml file.

Minimal working workflow for interactive mode:

name: Claude Code
on:
  issue_comment:
    types: [created]
  pull_request_review_comment:
    types: [created]

jobs:
  claude:
    runs-on: ubuntu-latest
    steps:
      - uses: anthropics/claude-code-action@v1
        with:
          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
          # That's all — nothing else is needed for @claude to work

The action determines the mode automatically: if no prompt is present in the workflow, it waits for an @claude trigger in a comment.

Working with @claude: What the Agent Can Do in a PR

Once configured, you can write in any PR or issue comment:

@claude implement the feature described in the issue
@claude fix the TypeError in the UserDashboard component
@claude review this PR for security issues
@claude add unit tests for the parseExpiry function

The agent reads the full context: the PR description, changed files, comment history, and your repository's CLAUDE.md. It then enters the agentic loop: plans, edits files, commits directly to the PR branch, and leaves a comment with the result.

Progress is shown as dynamic checkboxes in the agent's comment — a convenient way to track what it is doing.

Automated Workflows: Prompt Without a Trigger

For tasks that do not require manual invocation:

name: Daily Report
on:
  schedule:
    - cron: "0 9 * * 1-5"  # weekdays at 9:00 UTC

jobs:
  report:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: anthropics/claude-code-action@v1
        with:
          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
          prompt: "Analyze yesterday's commits and open issues, and produce a brief report"
          claude_args: "--model claude-opus-4 --max-turns 5"

The claude_args parameter passes CLI flags directly, just as if you were running claude in the terminal. You can pass --model, --max-turns, --allowedTools, --mcp-config — anything the CLI supports.

Automatic review of every PR on open:

name: Code Review on PR
on:
  pull_request:
    types: [opened, synchronize]

jobs:
  review:
    runs-on: ubuntu-latest
    steps:
      - uses: anthropics/claude-code-action@v1
        with:
          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
          prompt: "Review this PR for bugs, security issues, and adherence to the project's style"
          claude_args: "--max-turns 3"

Using Plugins and Skills

The prompt field can contain not just plain text, but also a skill invocation or a command from a plugin. For example, install the code-review plugin from the official marketplace and invoke its skill:

- 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 ${{ github.repository }}/pull/${{ github.event.pull_request.number }}"

For skills from the repository itself — run actions/checkout first, then the action.

Code Review: Managed Service

Separate from claude-code-action, there is Code Review — a managed service that runs on Anthropic's infrastructure (not your runners). Available for Team and Enterprise subscriptions.

The differences are significant:

• No YAML file or workflow configuration required
• Launches a fleet of specialized agents in parallel
• Each agent looks for a distinct class of problems; a verification pass follows
• Results appear as inline comments directly on code lines in the diff, marked with 🔴 (bug before merge) and 🟡 (nit)
• Average time — 20 minutes; average cost — $15–25 per review

Behavior can be customized via two files in the repository root:

• CLAUDE.md — general project rules (violations → nit level)
• REVIEW.md — review-specific instructions, injected as the highest priority into every agent in the fleet

Example REVIEW.md that restricts "important" findings to production bugs only:

# Review instructions


::widget{id="rc-3"}


::widget{id="rc-2"}


::widget{id="rc-1"}

## What counts as Important
Only things that will break production behavior: incorrect logic,
unscoped DB queries, PII in logs. Style — Nit at most.

## Nit limit
No more than 5 Nits per review; the rest — as "plus N similar" in the summary.

## Do not check
- Anything covered by CI (linting, types, formatting)
- Files under src/gen/ and any *.lock files

You can manually trigger a review by commenting @claude review on a PR.

Enterprise: Bedrock and Vertex AI

For organizations with data residency requirements — claude-code-action supports Amazon Bedrock and Google Vertex AI. Instead of ANTHROPIC_API_KEY, OIDC authentication is used:

# Amazon Bedrock
- uses: anthropics/claude-code-action@v1
  with:
    use_bedrock: "true"
    github_token: ${{ steps.app-token.outputs.token }}
    claude_args: '--model us.anthropic.claude-sonnet-4-6 --max-turns 10'

Note that Bedrock models use a regional prefix in their name (us.anthropic.claude-sonnet-4-6). Vertex uses a different format (claude-sonnet-4-5@20250929). When switching to a cloud provider, this is one of the most common sources of errors.

A Few Practical Considerations

Cost. Each @claude in a comment = GitHub Actions minutes + API tokens. With pull_request: synchronize, the agent runs on every push, which adds up quickly. Limit --max-turns and use concurrency at the workflow level so that a new push cancels the previous run.

Security. Never put API keys directly in YAML. The ANTHROPIC_API_KEY secret belongs in Settings → Secrets. For an explanation of why bypassPermissions is dangerous in the context of prompt injection, see Permissions Model, Security, and Trust.

CLAUDE.md in the repository. The agent reads it exactly as it does during local execution. This is the primary way to pass project context: code style, forbidden patterns, directory structure. Without it, the agent operates blind with respect to team conventions — covered in detail in CLAUDE.md and the Memory System.

Version @v1. The current major version is @v1 (released August 2025). If you have older workflows using @beta with parameters like mode, direct_prompt, or custom_instructions — that is the beta version with an incompatible API. Upgrading is straightforward: replace @beta with @v1, rename direct_prompt → prompt, and move the remaining options into claude_args.

See also

• Claude Agent SDK: Programmatic Agent Assembly — the engine that powers claude-code-action
• GitLab CI/CD and Headless Automation — an equivalent integration for GitLab pipelines
• Skills — Portable Skills — how to invoke skills from a prompt in Actions
• Plugins and Marketplace — installing plugins in a workflow
• CLAUDE.md and the Memory System — how project context affects the agent in CI
• Permissions Model, Security, and Trust — why it matters to restrict agent permissions in public repositories
• Practice: GitHub, Databases, and Web APIs via MCP — GitHub MCP Server as a complement to the Actions integration