mirror of
https://github.com/pacnpal/Claude-code-review.git
synced 2025-12-20 04:11:04 -05:00
ffacd0a72a
- Add Claude Sonnet 4.5 and Node 20 badges - Document technical details: model config, retry logic, timeouts - Add Limitations section covering diff size, timeouts, and costs - Add comprehensive Troubleshooting section with common issues - Add FAQ section answering common user questions - Expand Setup with environment protection guidance - Update Table of Contents with new sections - Clarify feature list with retry and rate limit handling
441 lines
14 KiB
Markdown
441 lines
14 KiB
Markdown
# Claude Code Review Action
|
|
|
|
|
|
|
|
|
|
|
|
|
|
A GitHub Action that performs automated code reviews using Claude Sonnet 4.5, Anthropic's latest AI model for code analysis.
|
|
|
|
## Why Use Claude Code Review?
|
|
|
|
- **Instant Feedback**: Get AI-powered code reviews immediately on every pull request
|
|
- **Consistent Quality**: Apply consistent review standards across your entire codebase
|
|
- **Save Time**: Catch common issues before human review, allowing reviewers to focus on architecture and logic
|
|
- **Learn & Improve**: Get educational feedback that helps developers improve their coding skills
|
|
- **24/7 Availability**: Reviews happen automatically, even outside business hours
|
|
|
|
## Table of Contents
|
|
|
|
- [Why Use Claude Code Review?](#why-use-claude-code-review)
|
|
- [Features](#features)
|
|
- [Usage](#usage)
|
|
- [Setup](#setup)
|
|
- [Inputs](#inputs)
|
|
- [Outputs](#outputs)
|
|
- [Review Format](#review-format)
|
|
- [Technical Details](#technical-details)
|
|
- [Limitations](#limitations)
|
|
- [Troubleshooting](#troubleshooting)
|
|
- [Development](#development)
|
|
- [Contributing](#contributing)
|
|
- [FAQ](#frequently-asked-questions)
|
|
- [License](#license)
|
|
- [Support](#support)
|
|
|
|
## Features
|
|
|
|
- 🤖 **AI-Powered Reviews**: Leverages Claude Sonnet 4.5 (claude-sonnet-4-5-20250929) for intelligent code analysis
|
|
- 🔍 **Comprehensive Analysis**: Examines code changes in pull requests thoroughly
|
|
- 💡 **Detailed Feedback**: Provides actionable feedback on code quality and structure
|
|
- 🐛 **Bug Detection**: Identifies potential issues and suggests improvements
|
|
- 🔒 **Security Scanning**: Checks for security vulnerabilities and risks
|
|
- ⚡ **Performance Insights**: Highlights performance implications of code changes
|
|
- 📋 **Best Practices**: Ensures adherence to coding standards and best practices
|
|
- 🎯 **Severity Ratings**: Categorizes issues by severity (Critical/High/Medium/Low)
|
|
- 🔄 **Automatic Retries**: Built-in retry logic with exponential backoff for reliability
|
|
- ⏱️ **Rate Limit Handling**: Automatically manages API rate limits
|
|
|
|
## Usage
|
|
|
|
Add this to your GitHub workflow file (e.g. `.github/workflows/review.yml`):
|
|
|
|
```yaml
|
|
name: Claude Code Review
|
|
|
|
permissions:
|
|
contents: read
|
|
pull-requests: write
|
|
|
|
on:
|
|
# Run on new/updated PRs
|
|
pull_request:
|
|
types: [opened, reopened, synchronize]
|
|
|
|
# Allow manual triggers for existing PRs
|
|
workflow_dispatch:
|
|
inputs:
|
|
pr_number:
|
|
description: 'Pull Request Number'
|
|
required: true
|
|
type: string
|
|
|
|
jobs:
|
|
code-review:
|
|
runs-on: ubuntu-latest
|
|
environment: development_environment
|
|
steps:
|
|
- uses: actions/checkout@v4
|
|
with:
|
|
fetch-depth: 0
|
|
|
|
- name: Run Claude Review
|
|
uses: pacnpal/claude-code-review@main
|
|
with:
|
|
github-token: ${{ secrets.GITHUB_TOKEN }}
|
|
anthropic-key: ${{ secrets.ANTHROPIC_API_KEY }}
|
|
pr-number: ${{ github.event.pull_request.number || inputs.pr_number }}
|
|
```
|
|
### Manual Trigger
|
|
|
|
For existing pull requests, you can manually trigger the review:
|
|
|
|
1. Click on "Claude Code Review" Action under the Actions tab
|
|
2. Click "Run Workflow"
|
|
3. Fill in the branch and pull request number
|
|
4. Click "Run Workflow"
|
|
|
|
### Disabling Auto-Review
|
|
|
|
You can disable automatic reviews and only use manual triggers by setting `auto-review: false`:
|
|
|
|
```yaml
|
|
- name: Run Claude Review
|
|
uses: pacnpal/claude-code-review@main
|
|
with:
|
|
github-token: ${{ secrets.GITHUB_TOKEN }}
|
|
anthropic-key: ${{ secrets.ANTHROPIC_API_KEY }}
|
|
pr-number: ${{ github.event.pull_request.number || inputs.pr_number }}
|
|
auto-review: false # Disables automatic reviews
|
|
```
|
|
|
|
You can also make it conditional based on labels or other criteria:
|
|
|
|
```yaml
|
|
- name: Run Claude Review
|
|
uses: pacnpal/claude-code-review@main
|
|
with:
|
|
github-token: ${{ secrets.GITHUB_TOKEN }}
|
|
anthropic-key: ${{ secrets.ANTHROPIC_API_KEY }}
|
|
pr-number: ${{ github.event.pull_request.number || inputs.pr_number }}
|
|
auto-review: ${{ contains(github.event.pull_request.labels.*.name, 'needs-review') }}
|
|
```
|
|
|
|
## Setup
|
|
|
|
### Prerequisites
|
|
|
|
- A GitHub repository
|
|
- An Anthropic API key ([Get one here](https://console.anthropic.com/))
|
|
- GitHub Actions enabled in your repository
|
|
|
|
### Configuration Steps
|
|
|
|
1. **Add Anthropic API Key**:
|
|
- Go to your repository Settings → Secrets and variables → Actions
|
|
- Click "New repository secret"
|
|
- Name: `ANTHROPIC_API_KEY`
|
|
- Value: Your Anthropic API key
|
|
- Click "Add secret"
|
|
|
|
2. **GitHub Token**:
|
|
- The `GITHUB_TOKEN` is automatically provided by GitHub Actions
|
|
- No additional configuration needed
|
|
|
|
3. **Set Permissions**:
|
|
- Ensure your workflow has proper permissions (see Usage example above)
|
|
- Required permissions: `contents: read` and `pull-requests: write`
|
|
- For organization repositories, you may need to enable workflows to create/approve pull requests in Settings
|
|
|
|
4. **Optional: Environment Protection**:
|
|
- For additional security, create a GitHub Environment (e.g., `development_environment`)
|
|
- Add `ANTHROPIC_API_KEY` as an environment secret instead of repository secret
|
|
- This provides additional control and approval gates for sensitive operations
|
|
|
|
## Inputs
|
|
|
|
| Input | Description | Required | Default |
|
|
|-------|-------------|----------|---------|
|
|
| `github-token` | GitHub token for API access | Yes | N/A |
|
|
| `anthropic-key` | Anthropic API key for Claude | Yes | N/A |
|
|
| `pr-number` | Pull request number to review | Yes | N/A |
|
|
| `auto-review` | Enable automatic code reviews (set to `false` to skip) | No | `true` |
|
|
|
|
## Outputs
|
|
|
|
| Output | Description |
|
|
|--------|-------------|
|
|
| `diff_size` | Size of the relevant code changes |
|
|
| `review` | Generated code review content |
|
|
|
|
## Review Format
|
|
|
|
The action provides detailed code reviews covering:
|
|
|
|
1. Potential conflicts with existing codebase
|
|
2. Code correctness and potential bugs
|
|
3. Security vulnerabilities and risks
|
|
4. Performance implications
|
|
5. Maintainability and readability issues
|
|
6. Adherence to best practices
|
|
7. Suggestions for improvements
|
|
|
|
Each issue found includes:
|
|
- Clear problem explanation
|
|
- Severity rating (Critical/High/Medium/Low)
|
|
- Specific recommendations
|
|
- Code examples where helpful
|
|
|
|
## Technical Details
|
|
|
|
### Model Configuration
|
|
|
|
- **Model**: Claude Sonnet 4.5 (`claude-sonnet-4-5-20250929`)
|
|
- **Max Tokens**: 4096 tokens per review
|
|
- **Temperature**: 0.7 for balanced creativity and consistency
|
|
- **Context**: 10 lines of context around each change (git diff -U10)
|
|
|
|
### Reliability Features
|
|
|
|
**Automatic Retry Logic**:
|
|
- Network failures are automatically retried up to 4 times
|
|
- Exponential backoff strategy (2s, 4s, 8s, 16s delays)
|
|
- Non-retryable errors (401, 403, 400) fail immediately
|
|
|
|
**Timeout Protection**:
|
|
- API requests timeout after 2 minutes
|
|
- Prevents hanging workflows on slow responses
|
|
|
|
**Rate Limit Handling**:
|
|
- Automatically respects `Retry-After` headers
|
|
- Graceful handling of 429 rate limit responses
|
|
|
|
### Diff Size Limits
|
|
|
|
- **Maximum Diff Size**: ~100KB (100,000 bytes)
|
|
- Large diffs are automatically truncated with a notice
|
|
- Helps stay within API token limits and ensures fast reviews
|
|
|
|
## Limitations
|
|
|
|
- **Diff Size**: Changes larger than ~100KB will be truncated
|
|
- **Review Timeout**: Reviews exceeding 2 minutes will timeout
|
|
- **PR State**: Can review closed PRs, but a warning is logged
|
|
- **File Types**: All text-based files are analyzed; binary files in diffs are ignored
|
|
- **API Costs**: Each review consumes Anthropic API credits based on diff size
|
|
|
|
## Troubleshooting
|
|
|
|
### Common Issues
|
|
|
|
**Issue**: "Failed to get PR details"
|
|
- **Solution**: Ensure `GITHUB_TOKEN` has `pull-requests: read` permission
|
|
- **Solution**: Verify the PR number is correct
|
|
|
|
**Issue**: "anthropic-key does not match expected format"
|
|
- **Solution**: Verify your API key starts with `sk-ant-`
|
|
- **Solution**: Check for extra spaces or newlines in the secret
|
|
|
|
**Issue**: "Diff is empty - no changes found"
|
|
- **Solution**: This is expected when comparing identical commits
|
|
- **Solution**: Ensure the PR has actual code changes
|
|
|
|
**Issue**: "Rate limited" or 429 errors
|
|
- **Solution**: The action will automatically retry with backoff
|
|
- **Solution**: Consider reducing review frequency if you hit limits often
|
|
- **Solution**: Check your Anthropic API rate limits and quotas
|
|
|
|
**Issue**: "API request timed out"
|
|
- **Solution**: This may happen with very large diffs (>100KB)
|
|
- **Solution**: Break large PRs into smaller, more focused changes
|
|
- **Solution**: The action will automatically truncate diffs that are too large
|
|
|
|
**Issue**: Action fails with authentication errors
|
|
- **Solution**: Verify `ANTHROPIC_API_KEY` is set correctly in repository secrets
|
|
- **Solution**: Ensure the API key is active and not expired
|
|
- **Solution**: Check that your Anthropic account has available credits
|
|
|
|
### Debug Mode
|
|
|
|
To enable verbose logging, add this to your workflow:
|
|
|
|
```yaml
|
|
- name: Run Claude Review
|
|
uses: pacnpal/claude-code-review@main
|
|
with:
|
|
github-token: ${{ secrets.GITHUB_TOKEN }}
|
|
anthropic-key: ${{ secrets.ANTHROPIC_API_KEY }}
|
|
pr-number: ${{ github.event.pull_request.number }}
|
|
env:
|
|
ACTIONS_STEP_DEBUG: true
|
|
```
|
|
|
|
## Example Review
|
|
|
|
```markdown
|
|
# Claude Code Review
|
|
|
|
1. **Potential conflicts with existing codebase**:
|
|
- No apparent conflicts identified
|
|
|
|
2. **Code correctness and potential bugs**:
|
|
- **Medium Severity**: Potential null pointer in user handling
|
|
- Recommendation: Add null check before accessing user object
|
|
|
|
3. **Security vulnerabilities and risks**:
|
|
- **High Severity**: SQL injection vulnerability in query construction
|
|
- Recommendation: Use parameterized queries
|
|
```
|
|
|
|
## Development
|
|
|
|
### Local Development Setup
|
|
|
|
1. **Clone the repository**:
|
|
```bash
|
|
git clone https://github.com/pacnpal/claude-code-review.git
|
|
cd claude-code-review
|
|
```
|
|
|
|
2. **Install dependencies**:
|
|
```bash
|
|
npm install
|
|
```
|
|
|
|
3. **Make your changes**:
|
|
- Edit `action.js` for core functionality
|
|
- The built output goes to `dist/index.js`
|
|
|
|
4. **Build the action**:
|
|
```bash
|
|
npm run build
|
|
```
|
|
This compiles `action.js` into `dist/index.js` using [@vercel/ncc](https://github.com/vercel/ncc)
|
|
|
|
5. **Run tests**:
|
|
```bash
|
|
npm test
|
|
```
|
|
|
|
### Project Structure
|
|
|
|
```
|
|
claude-code-review/
|
|
├── action.js # Main action logic
|
|
├── action.yml # Action metadata
|
|
├── dist/ # Built output (committed)
|
|
│ └── index.js # Compiled action
|
|
├── package.json # Dependencies
|
|
└── README.md # Documentation
|
|
```
|
|
|
|
### Testing Changes
|
|
|
|
- Test your changes in a fork before submitting a PR
|
|
- Use the `workflow_dispatch` trigger for manual testing
|
|
- Ensure `npm run build` completes without errors
|
|
- Verify all tests pass with `npm test`
|
|
|
|
## Contributing
|
|
|
|
Contributions are welcome! Please:
|
|
|
|
1. Fork the repository
|
|
2. Create a feature branch
|
|
3. Make your changes
|
|
4. Run tests
|
|
5. Submit a pull request
|
|
|
|
## Frequently Asked Questions
|
|
|
|
### How much does it cost?
|
|
|
|
The action is free, but you'll need an Anthropic API subscription. Costs vary based on:
|
|
- Diff size (larger diffs = more tokens)
|
|
- Review frequency (more PRs = more API calls)
|
|
- Current Claude API pricing (check [Anthropic's pricing](https://www.anthropic.com/pricing))
|
|
|
|
Typical small PR review (~1-2KB diff) costs a few cents.
|
|
|
|
### Can I use this with private repositories?
|
|
|
|
Yes! The action works with both public and private repositories. Just ensure:
|
|
- GitHub Actions is enabled for your repository
|
|
- You've added the `ANTHROPIC_API_KEY` secret
|
|
- Workflow permissions are properly configured
|
|
|
|
### Will this slow down my CI/CD pipeline?
|
|
|
|
The action runs asynchronously and doesn't block other checks. Typical review times:
|
|
- Small PRs (<10KB): 10-30 seconds
|
|
- Medium PRs (10-50KB): 30-60 seconds
|
|
- Large PRs (50-100KB): 60-120 seconds
|
|
|
|
You can also use `auto-review: false` to only run reviews on-demand.
|
|
|
|
### Can I customize the review criteria?
|
|
|
|
Currently, the review criteria are built into the action. Future versions may support custom prompts. You can:
|
|
- Fork the repository and modify `action.js` to customize the prompt
|
|
- Use the review as a baseline and add custom checks with other actions
|
|
|
|
### Does it support languages other than English?
|
|
|
|
The action's prompts are in English, but Claude can analyze code in any programming language. Review comments will be in English.
|
|
|
|
### What happens if my diff is too large?
|
|
|
|
Diffs larger than ~100KB are automatically truncated. A notice is added to the review indicating truncation. For large PRs:
|
|
- Consider breaking them into smaller, focused changes
|
|
- The most important changes (first ~100KB) will still be reviewed
|
|
|
|
### Can I run this on forked PRs?
|
|
|
|
Yes, but be cautious with secrets. Use GitHub's `pull_request_target` event with proper security:
|
|
- Don't expose secrets to untrusted code
|
|
- Consider requiring manual approval for fork PRs
|
|
- Review GitHub's [security hardening guide](https://docs.github.com/en/actions/security-guides/security-hardening-for-github-actions)
|
|
|
|
### How do I prevent reviews on draft PRs?
|
|
|
|
Add a condition to your workflow:
|
|
|
|
```yaml
|
|
jobs:
|
|
code-review:
|
|
if: github.event.pull_request.draft == false
|
|
runs-on: ubuntu-latest
|
|
# ... rest of job
|
|
```
|
|
|
|
## License
|
|
|
|
MIT License - see the [LICENSE](LICENSE) file for details
|
|
|
|
## Support
|
|
|
|
### Getting Help
|
|
|
|
- 🐛 **Bug Reports**: [Open an issue](https://github.com/pacnpal/claude-code-review/issues/new) with details and reproduction steps
|
|
- 💡 **Feature Requests**: [Create an issue](https://github.com/pacnpal/claude-code-review/issues/new) describing your use case
|
|
- 🤝 **Contributions**: Submit a PR following our contribution guidelines
|
|
- 📧 **Questions**: Open a discussion or contact the maintainers
|
|
|
|
### Resources
|
|
|
|
- [Anthropic Claude Documentation](https://docs.anthropic.com/)
|
|
- [GitHub Actions Documentation](https://docs.github.com/en/actions)
|
|
- [Action Marketplace Listing](https://github.com/marketplace/actions/claude-code-review)
|
|
|
|
## Acknowledgments
|
|
|
|
Built with:
|
|
- [Anthropic Claude API](https://www.anthropic.com/claude) - AI-powered code analysis
|
|
- [GitHub Actions](https://github.com/features/actions) - CI/CD automation platform
|
|
- [@actions/core](https://github.com/actions/toolkit/tree/main/packages/core) - GitHub Actions toolkit
|
|
- [@vercel/ncc](https://github.com/vercel/ncc) - Node.js bundler
|
|
|
|
---
|
|
|
|
**Made with ❤️ by PacNPal** | [Report Bug](https://github.com/pacnpal/claude-code-review/issues) | [Request Feature](https://github.com/pacnpal/claude-code-review/issues)
|