mirror of
https://github.com/pacnpal/Claude-code-review.git
synced 2025-12-19 20:01:05 -05:00
Enhance README with comprehensive documentation improvements
- 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
This commit is contained in:
Claude
164
README.md
164
README.md
@@ -2,6 +2,8 @@
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
A GitHub Action that performs automated code reviews using Claude Sonnet 4.5, Anthropic's latest AI model for code analysis.
|
||||
|
||||
@@ -22,14 +24,18 @@ A GitHub Action that performs automated code reviews using Claude Sonnet 4.5, An
|
||||
- [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 for intelligent code analysis
|
||||
- 🤖 **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
|
||||
@@ -37,6 +43,8 @@ A GitHub Action that performs automated code reviews using Claude Sonnet 4.5, An
|
||||
- ⚡ **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
|
||||
|
||||
@@ -134,9 +142,15 @@ You can also make it conditional based on labels or other criteria:
|
||||
- The `GITHUB_TOKEN` is automatically provided by GitHub Actions
|
||||
- No additional configuration needed
|
||||
|
||||
3. **Set Permissions** (if 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
|
||||
|
||||
@@ -172,6 +186,90 @@ Each issue found includes:
|
||||
- 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
|
||||
@@ -248,6 +346,68 @@ Contributions are welcome! Please:
|
||||
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
|
||||
|
||||
Reference in New Issue
Block a user