Claude Auto Review GitHub Action

Automated code review using Claude AI with configurable project context and incremental review capabilities.

Overview

This GitHub Action provides automated code reviews for your pull requests using Claude AI. It features:

Smart incremental reviews - Only flags new issues in subsequent commits
Configurable prompts - Customize review focus with project-specific context
Multiple trigger modes - Automatic on PR open or manual via comments
Security-focused - Built-in emphasis on security, performance, and best practices

Review Mode & Capabilities

This action operates in read-only review mode to ensure safe and reliable operation in CI/CD environments.

What Claude Can Do ✅

Analyze code changes - Review all code modifications in pull requests
Read project files - Access repository files for context
Provide feedback - Post detailed review comments and suggestions
Identify issues - Detect bugs, security concerns, and best practice violations
Track incremental changes - Compare new commits against previous reviews
Understand context - Read existing comments and PR discussions

What Claude Cannot Do ❌

Execute shell commands - No npm install, build scripts, or CLI tools
Set up environments - No dependency installation or environment configuration
Run tests or builds - Code execution is not permitted
Modify local files - Read-only access to the repository
Clone repositories - No external resource fetching

Prerequisites

Anthropic API Key: Obtain an API key from Anthropic Console
Repository Secret: Add your API key as ANTHROPIC_API_KEY in repository secrets
Permissions: Ensure the workflow has appropriate GitHub token permissions

Quick Start

Create a workflow file (e.g., .github/workflows/claude-review.yml):

name: Claude Auto Review

on:
  pull_request:
    types: [opened]
    branches: [main] # or your default branch
  issue_comment:
    types: [created]

jobs:
  review:
    runs-on: ubuntu-latest
    timeout-minutes: 60 # Recommended: control timeout at job level
    if: |
      github.event_name == 'pull_request'
      || (
        github.event_name == 'issue_comment'
        && github.event.issue.pull_request
        && contains(github.event.comment.body, '@claude review')
      )
    permissions:
      contents: read
      pull-requests: write
      issues: write
      id-token: write
    steps:
      - name: Checkout
        uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - name: Claude Review
        uses: WalletConnect/actions/claude/auto-review@master
        with:
          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}

Configuration Options

Inputs

Input	Required	Default	Description
`anthropic_api_key`	✅	-	Your Anthropic API key for Claude access
`model`	❌	`claude-sonnet-4-6`	Claude model to use for reviews
`timeout_minutes`	❌	-	⚠️ DEPRECATED: Accepted but ignored by v1 (no effect). Use job-level `timeout-minutes` instead.
`custom_prompt`	❌	-	Complete custom prompt override. Ignores all other prompt inputs if provided
`project_context`	❌	-	Additional project-specific context to help Claude understand your codebase
`comment_pr_findings`	❌	`true`	Automatically post inline PR comments for findings saved to `findings.json`
`force_breaking_changes_agent`	❌	`false`	Force breaking changes subagent regardless of file heuristic
`force_license_compliance_agent`	❌	`false`	Force license compliance agent regardless of heuristic
`auto_approve`	❌	`false`	Enable AI-powered auto-approval after review
`auto_approve_app_id`	When `auto_approve` is `true`	-	GitHub App ID used to generate a token for PR approval
`auto_approve_private_key`	When `auto_approve` is `true`	-	GitHub App private key for PR approval
`auto_approve_scope_prompt`	❌	-	Instructions telling Claude when to approve or reject. Provide repo-specific criteria

Usage Examples

Basic Usage

- name: Claude Review
  uses: WalletConnect/actions/claude/auto-review@master
  with:
    anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}

With Project Context

- name: Claude Review
  uses: WalletConnect/actions/claude/auto-review@master
  with:
    anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
    project_context: |
      This is a React TypeScript application using:
      - Next.js with App Router
      - PostgreSQL with Prisma ORM
      - tRPC for API layer
      - Jest for testing

      Key considerations:
      - Follow React Query patterns for data fetching
      - Ensure proper TypeScript strict mode compliance
      - Maintain API route security with proper validation

With Custom Model and Timeout

jobs:
  review:
    runs-on: ubuntu-latest
    timeout-minutes: 90 # Job-level timeout (recommended)
    steps:
      - name: Claude Review
        uses: WalletConnect/actions/claude/auto-review@master
        with:
          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
          model: claude-sonnet-4-6

With Complete Custom Prompt

- name: Claude Review
  uses: WalletConnect/actions/claude/auto-review@master
  with:
    anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
    custom_prompt: |
      Review this Python Django pull request focusing specifically on:
      1. Django best practices and security patterns
      2. Database migration safety
      3. API endpoint security and validation
      4. Test coverage for new functionality
      5. Performance implications of ORM queries

      Provide specific, actionable feedback with code examples.

Workflow Integration

Automatic Reviews

The action can automatically review PRs when they are opened:

on:
  pull_request:
    types: [opened, synchronize] # Include synchronize for incremental reviews
    branches: [main, develop]

Manual Triggers

Enable manual reviews by commenting @claude review on any PR:

on:
  issue_comment:
    types: [created]

jobs:
  review:
    if: |
      github.event.issue.pull_request
      && contains(github.event.comment.body, '@claude review')

Combined Approach (Recommended)

on:
  pull_request:
    types: [opened]
    branches: [main]
  issue_comment:
    types: [created]

jobs:
  review:
    if: |
      github.event_name == 'pull_request'
      || (
        github.event_name == 'issue_comment'
        && github.event.issue.pull_request
        && contains(github.event.comment.body, '@claude review')
      )

Review Features

Incremental Reviews

For PR updates (synchronize events) or manual @claude review triggers after the initial review, Claude:

✅ Checks existing review comments
✅ Only flags new issues in latest commits
✅ Notes if previously flagged issues were resolved
✅ Avoids repeating previous feedback

Built-in Review Focus Areas

The default prompt emphasizes:

Code Quality - Best practices for your tech stack
Security - Authentication, API endpoints, data handling
Performance - Frontend and backend optimization opportunities
Testing - Coverage and quality of test implementations
Type Safety - Proper usage of type systems
Error Handling - Edge cases and error scenarios
Maintainability - Code readability and structure
PR Size Assessment - Flags oversized PRs (>15 files or >800 lines) with suggestions for splitting
Static Resource Caching - Validates Cache-Control headers for static immutable resources (fonts, images, CSS, JS) to ensure proper caching (1 year minimum for immutable assets)
External Dependencies - Flags URLs pointing to domains outside approved company domains
Dependency License Compliance - Flags non-permissive licenses (GPL, AGPL, SSPL) in newly added dependencies across all ecosystems

PR Size Detection

Claude automatically detects oversized PRs and provides actionable guidance on breaking them up:

Thresholds: >15 files changed OR >800 lines modified
Severity: HIGH (maintainability category)
Split Suggestions: Analyzes changes both by logical concern (refactoring vs features vs bug fixes) and by file/directory groupings to recommend 2-4 focused PRs

This helps prevent "GOD PRs" that are difficult to review thoroughly, more likely to hide bugs, and prone to merge conflicts.

Dependency License Compliance (Subagent)

License compliance runs as a conditional subagent — it only spawns when the PR modifies dependency manifest or lockfiles, keeping the main review context focused.

Trigger: Any dependency manifest file changed (package.json, go.mod, Cargo.toml, pyproject.toml, requirements*.txt, Gemfile, lockfiles, etc.)
Force override: Set force_license_compliance_agent: 'true' to always run
ID prefix: Findings use lic- prefixed IDs (e.g., lic-gpl-library-a3f1)
Ecosystems: Node.js (npm/pnpm/yarn), Go, Rust, Python, Ruby, PHP, Java/Kotlin
Permissive (OK): MIT, Apache-2.0, BSD, ISC, Unlicense, CC0
Restrictive (HIGH): GPL, AGPL, SSPL — strong copyleft obligations
Weak Copyleft (MEDIUM): LGPL, MPL, EPL — may be acceptable, flagged for review
Unknown (LOW): Packages whose license cannot be confidently determined
Dev dependencies: Severity reduced by one level (not distributed with software)
Dual-licensed: Evaluates the most permissive available option

Inline Findings Comments (New)

After Claude reviews the PR, this action automatically extracts findings from Claude's comment
Findings are parsed and structured into findings.json format
Inline PR review comments are posted automatically for each finding with file/line context
Disable this behaviour with comment_pr_findings: 'false' or by exporting SILENCE_AUTO_REVIEW_COMMENTS=true
Requires pull-requests: write permission, GitHub CLI (gh), and jq on the runner (auto-installed if missing)

Breaking Changes Detection Agent

The auto-review action includes a specialized breaking changes subagent that is conditionally spawned based on PR file analysis. When triggered, the main Claude agent launches a Task subagent that reads its spec from agents/review-breaking-changes.md.

Trigger conditions (any match spawns the agent):

action.yml/action.yaml files modified
Workflow YAML files modified (.github/workflows/*.yml)
Package manifests changed (package.json, go.mod, pyproject.toml, Cargo.toml, setup.py)
Type definition files changed (.d.ts, types.ts, interfaces.ts)
API route/controller files changed
Schema/migration files changed
Files deleted (status: removed)
Breaking change keywords detected in patch content (inputs:, outputs:, required:, exports, etc.)
PR has breaking or breaking-change label

Skip conditions:

PR has skip-review label
All files are documentation-only (.md, .txt, .rst)
All files are test-only

ID prefix convention: All findings from the breaking changes agent use the brk- prefix (e.g., brk-action-remove-timeout-input-e4f1). This prefix is used for agent attribution in findings.json.

Force override: Set force_breaking_changes_agent: "true" to always spawn the agent regardless of heuristic.

Auto-Approve (AI-Powered)

The auto-approve feature lets Claude automatically approve PRs that pass review, using a repo-specific scope prompt to decide. This is useful for satisfying org-level "required approvals" rules on low-risk PRs (e.g. Terraform config changes, documentation updates).

How It Works

The normal auto-review runs (unchanged)
Findings are extracted into findings.json (unchanged)
Claude evaluates the diff, changed files, and review findings against your auto_approve_scope_prompt
If Claude decides the PR is safe, a GitHub App token is generated and the PR is approved
If Claude decides the PR is unsafe (or has CRITICAL/HIGH findings), approval is skipped

Setup

1. Create a GitHub App in your org (Settings → Developer settings → GitHub Apps → New GitHub App):

Name: e.g. Claude Reviewer (must be unique across GitHub)
Homepage URL: your org's GitHub URL (required field, any URL works)
Permissions: Repository permissions → Pull Requests → Read & Write
Webhook: uncheck "Active" (no webhook needed)
Installation: "Only on this account"

2. Generate a private key: on the App's settings page, scroll to "Private keys" → "Generate a private key". Save the downloaded .pem file.

3. Install the App on the target repository (or all repositories): App settings → "Install App" → select your org → choose repositories.

4. Add org secrets (Org Settings → Secrets and variables → Actions → New organization secret):

CLAUDE_REVIEWER_APP_ID — the App ID (visible on the App's "General" settings page)
CLAUDE_REVIEWER_PRIVATE_KEY — the full contents of the .pem private key file
Set repository access to "All repositories" or select specific repos that need auto-approve

Usage

- name: Claude Review
  uses: WalletConnect/actions/claude/auto-review@master
  with:
    anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
    auto_approve: "true"
    auto_approve_app_id: ${{ secrets.CLAUDE_REVIEWER_APP_ID }}
    auto_approve_private_key: ${{ secrets.CLAUDE_REVIEWER_PRIVATE_KEY }}
    auto_approve_scope_prompt: |
      Only approve Terraform infrastructure changes.
      All changed files must be under infrastructure/, monitoring/, or .github/workflows/*terraform*.
      If the PR includes any non-Terraform files, reject.

      Do NOT approve if:
      - Resources are being destroyed or removed
      - Database or storage resources are deleted
      - force_destroy is enabled or prevent_destroy is removed
      - Any change that could cause data loss

      Approve if changes are safe: new resources, variable updates, policy changes, monitoring config.

The scope prompt is fully customizable per repository. Other examples:

# Documentation-only auto-approve
auto_approve_scope_prompt: |
  Only approve if every changed file is documentation (.md, .txt, .rst).
  Reject if any code files are modified.

# Dependency update auto-approve
auto_approve_scope_prompt: |
  Only approve dependency version bumps (package.json, lockfiles).
  Reject if any source code files are modified.
  Reject if a dependency is added or removed (only version changes are safe).

Best Practices

1. Provide Project Context

Always include relevant project context to get more targeted reviews:

project_context: |
  Tech Stack: React + TypeScript + Node.js
  Database: MongoDB with Mongoose
  Testing: Jest + React Testing Library
  Deployment: Docker on AWS ECS

  Focus Areas:
  - MongoDB query optimization
  - React performance patterns
  - Proper error boundaries usage
  - Docker security practices

⚠️ Important: The project_context content is inserted into a bash script during execution. Avoid using backticks, dollar signs followed by parentheses, or other shell-interpretable syntax as they will be executed as shell commands and cause the action to fail. Use plain text descriptions without code formatting markers.

2. Use Branch Protection

Consider requiring Claude reviews before merging:

on:
  pull_request:
    types: [opened, synchronize]

3. Combine with Other Checks

Claude reviews complement (don't replace) automated testing:

jobs:
  tests:
    runs-on: ubuntu-latest
    steps:
      # Your test steps

  claude-review:
    needs: tests # Run after tests pass
    # Claude review steps

Troubleshooting

Common Issues

"Action timed out"

Increase job-level timeout-minutes for large PRs
If Claude flags your PR as too large, follow the split suggestions to create smaller, focused PRs

"API key invalid"

Verify ANTHROPIC_API_KEY secret is set correctly
Ensure API key has sufficient credits/quota

"No review posted"

Check GitHub token permissions include pull-requests: write
Verify workflow triggers are configured correctly
Confirm gh CLI and jq are available on the runner (auto-installed on Ubuntu/macOS)
Inline comments require Claude to find issues—PRs with no issues will only have a summary comment

"Review quality is generic"

Add specific project_context about your tech stack
Include coding standards and architectural patterns
Mention specific areas of concern for your project

Getting Better Reviews

Be Specific: Include detailed project context about your architecture, patterns, and concerns
Update Context: Keep project context current as your codebase evolves
Use Manual Triggers: Comment @claude review for focused reviews of specific changes
Iterate on Prompts: Refine custom prompts based on review quality

Security Considerations

Access Control

Only users with repository write access can trigger the Claude Code Action
GitHub Apps and bots are blocked by default for additional security
Authentication tokens are short-lived and scoped to the specific repository

Required GitHub App Permissions

The Claude GitHub App requires these specific permissions:

Pull Requests: Read/write access to create and update pull request reviews
Issues: Read/write access to respond to issue comments
Contents: Read/write access to analyze and modify repository files

Credential Security

⚠️ CRITICAL: Never hardcode your Anthropic API key or OAuth token in workflow files!

✅ Correct: Always store credentials in GitHub Secrets: ${{ secrets.ANTHROPIC_API_KEY }}
❌ Incorrect: Embedding API keys directly in workflow YAML files
API keys are securely handled through GitHub Secrets infrastructure
All communication between the action and Anthropic's API uses HTTPS

Additional Security Features

All commits made by Claude are automatically signed for authenticity verification
The action only has read access to code and write access to PR comments
No code or sensitive data is stored by the action beyond the GitHub workflow execution
Short-lived tokens ensure minimal security exposure window

For Complete Security Details

For comprehensive security information and best practices, see the official Claude Code Action security documentation.

Support

For issues with the action itself, please check:

GitHub Actions logs for detailed error messages
Anthropic API status and quotas
Repository permissions and secrets configuration

Uh oh!

FilesExpand file tree

README.md

Latest commit

History