AI Code Review Action

A reusable GitHub Action for automated code review using Claude Code.

Features

• Two-phase review: codebase analysis + PR review
• Incremental review support (only review new commits on PR updates)
• Posts review summary and inline comments to PR
• Configurable conventions path for project-specific rules
• Supports multiple Claude models

Usage

Basic Usage (API Key)

name: AI Code Review

on:
  pull_request:
    types: [opened, synchronize, reopened]

jobs:
  review:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - name: AI Code Review
        uses: team247/auto-code-review@main
        with:
          api-key: ${{ secrets.ANTHROPIC_API_KEY }}
          github-token: ${{ secrets.GITHUB_TOKEN }}
          base-sha: ${{ github.event.pull_request.base.sha }}
          head-sha: ${{ github.event.pull_request.head.sha }}
          event-action: ${{ github.event.action }}
          before-sha: ${{ github.event.before }}

Basic Usage (OAuth Token)

Pro and Max users can use OAuth token authentication (run claude setup-token locally to generate):

name: AI Code Review

on:
  pull_request:
    types: [opened, synchronize, reopened]

jobs:
  review:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - name: AI Code Review
        uses: team247/auto-code-review@main
        with:
          oauth-token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}
          github-token: ${{ secrets.GITHUB_TOKEN }}
          base-sha: ${{ github.event.pull_request.base.sha }}
          head-sha: ${{ github.event.pull_request.head.sha }}
          event-action: ${{ github.event.action }}
          before-sha: ${{ github.event.before }}

Advanced Usage

jobs:
  review:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - name: AI Code Review with Options
        uses: team247/auto-code-review@main
        with:
          api-key: ${{ secrets.ANTHROPIC_API_KEY }}
          github-token: ${{ secrets.GITHUB_TOKEN }}
          base-sha: ${{ github.event.pull_request.base.sha }}
          head-sha: ${{ github.event.pull_request.head.sha }}
          event-action: ${{ github.event.action }}
          before-sha: ${{ github.event.before }}
          model: "sonnet"           # Default: sonnet (options: haiku, sonnet, opus)
          post-review: "true"       # Default: true (set "false" to skip PR comments)
          conventions-path: "docs/conventions"  # Path to conventions files
          review-mode: "auto"       # Default: auto (options: auto, full, incremental)

Inputs

Input	Required	Default	Description
api-key	No*	-	Anthropic API key for Claude
oauth-token	No*	-	Claude Code OAuth token (Pro/Max users, takes priority over api-key)
cursor-api-key	No	-	Cursor API key (falls back to api-key)
github-token	No	github.token	GitHub token for posting comments
base-sha	Yes	-	Base commit SHA (target branch)
head-sha	Yes	-	Head commit SHA (PR branch)
event-action	No	opened	GitHub event action
before-sha	No	-	Previous head SHA (for synchronize events)
model	No	sonnet	Claude model to use
post-review	No	true	Whether to post comments to PR
conventions-path	No	docs/conventions	Path to conventions directory
review-mode	No	auto	Review mode: auto, full, incremental

* Either api-key or oauth-token is required. If both are provided, oauth-token takes priority.

Outputs

Output	Description
review-report	Path to the generated review report
blocking-issues-count	Number of blocking issues found
suggestions-count	Number of suggestions found

Project Conventions

The action looks for conventions in the specified conventions-path directory (default: docs/conventions).

Create these files to customize the review behavior:

• global-conventions.md - Global coding standards
• project_conventions.md - Auto-generated from codebase analysis

First Run Behavior

On the first PR review, the action analyzes your codebase and generates project_conventions.md. This file is cached and used for subsequent reviews.

Example Conventions File

# Project Coding Conventions

## Language
- TypeScript with strict mode
- ESLint for linting

## Style
- 2 spaces for indentation
- Single quotes for strings
- Semicolons required

## Testing
- Jest for unit tests
- 80% minimum coverage

Troubleshooting

Authentication Issues

Add authentication to your repository secrets:

• ANTHROPIC_API_KEY - For API key authentication
• CLAUDE_CODE_OAUTH_TOKEN - For OAuth token authentication (Pro/Max users can generate this by running claude setup-token locally)

If both are configured, OAuth token takes priority.

No Comments Posted

• Check that github-token has pull-requests: write permission
• Verify PR_NUMBER is available in the workflow context

Incremental Review Not Working

• Ensure event-action is synchronize for PR updates
• Provide before-sha with the previous commit SHA

Development

Running Locally

# Test the action
bash action.sh <base_sha> <head_sha>

Project Structure

auto-code-review/
├── action.yml           # Action metadata
├── action.sh            # Action entrypoint
├── comment-review.js    # PR comment poster
├── prompts/
│   ├── code-analyze.md  # Codebase analysis prompt
│   ├── code-review.md   # PR review prompt
│   └── generate-json.md # JSON summary generation
└── README.md

License

MIT