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.
|
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)
|
- [Inputs](#inputs)
|
||||||
- [Outputs](#outputs)
|
- [Outputs](#outputs)
|
||||||
- [Review Format](#review-format)
|
- [Review Format](#review-format)
|
||||||
|
- [Technical Details](#technical-details)
|
||||||
|
- [Limitations](#limitations)
|
||||||
|
- [Troubleshooting](#troubleshooting)
|
||||||
- [Development](#development)
|
- [Development](#development)
|
||||||
- [Contributing](#contributing)
|
- [Contributing](#contributing)
|
||||||
|
- [FAQ](#frequently-asked-questions)
|
||||||
- [License](#license)
|
- [License](#license)
|
||||||
- [Support](#support)
|
- [Support](#support)
|
||||||
|
|
||||||
## Features
|
## 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
|
- 🔍 **Comprehensive Analysis**: Examines code changes in pull requests thoroughly
|
||||||
- 💡 **Detailed Feedback**: Provides actionable feedback on code quality and structure
|
- 💡 **Detailed Feedback**: Provides actionable feedback on code quality and structure
|
||||||
- 🐛 **Bug Detection**: Identifies potential issues and suggests improvements
|
- 🐛 **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
|
- ⚡ **Performance Insights**: Highlights performance implications of code changes
|
||||||
- 📋 **Best Practices**: Ensures adherence to coding standards and best practices
|
- 📋 **Best Practices**: Ensures adherence to coding standards and best practices
|
||||||
- 🎯 **Severity Ratings**: Categorizes issues by severity (Critical/High/Medium/Low)
|
- 🎯 **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
|
## 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
|
- The `GITHUB_TOKEN` is automatically provided by GitHub Actions
|
||||||
- No additional configuration needed
|
- No additional configuration needed
|
||||||
|
|
||||||
3. **Set Permissions** (if needed):
|
3. **Set Permissions**:
|
||||||
- Ensure your workflow has proper permissions (see Usage example above)
|
- Ensure your workflow has proper permissions (see Usage example above)
|
||||||
- Required permissions: `contents: read` and `pull-requests: write`
|
- 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
|
## Inputs
|
||||||
|
|
||||||
@@ -172,6 +186,90 @@ Each issue found includes:
|
|||||||
- Specific recommendations
|
- Specific recommendations
|
||||||
- Code examples where helpful
|
- 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
|
## Example Review
|
||||||
|
|
||||||
```markdown
|
```markdown
|
||||||
@@ -248,6 +346,68 @@ Contributions are welcome! Please:
|
|||||||
4. Run tests
|
4. Run tests
|
||||||
5. Submit a pull request
|
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
|
## License
|
||||||
|
|
||||||
MIT License - see the [LICENSE](LICENSE) file for details
|
MIT License - see the [LICENSE](LICENSE) file for details
|
||||||
|
|||||||
Reference in New Issue
Block a user