feat(guide): add thinking keywords, GitHub Actions examples, and improvement recommendations
Documentation enhancements: - Add inline thinking keywords section (think, think hard, ultrathink) with usage examples - Create examples/github-actions/ directory with 3 ready-to-use workflows: * Auto PR review with inline comments * Security review on every PR * Issue triage with label suggestions - Add comprehensive IMPROVEMENT_RECOMMENDATIONS.md with prioritized action items Improvements based on zebbern/claude-code-guide analysis: - Enhanced troubleshooting guidance - Format enhancements (badges, collapsible tables, C-style comments) - Security/performance/workflow pitfalls sections - DeepSeek integration documentation - One-shot health check scripts Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
This commit is contained in:
Florian BRUNIAUX
parent
29d922af72
commit
87994bb797
6 changed files with 958 additions and 0 deletions
203
examples/github-actions/README.md
Normal file
203
examples/github-actions/README.md
Normal file
|
|
@ -0,0 +1,203 @@
|
|||
# GitHub Actions Workflows for Claude Code
|
||||
|
||||
Ready-to-use GitHub Actions workflows that integrate Claude Code into your CI/CD pipeline.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
1. **Install the Claude GitHub App** on your org/repo (required for Actions to comment on PRs/issues)
|
||||
2. **Add API Key Secret**: In your repo, go to Settings → Secrets and variables → Actions → New repository secret
|
||||
- Name: `ANTHROPIC_API_KEY`
|
||||
- Value: Your Anthropic API key from [console.anthropic.com](https://console.anthropic.com)
|
||||
3. **Copy Workflows**: Place these `.yml` files in `.github/workflows/` directory
|
||||
4. **Test**: Open a test PR or issue to see them run
|
||||
|
||||
## Available Workflows
|
||||
|
||||
### 1. Auto PR Review (`claude-pr-auto-review.yml`)
|
||||
|
||||
Creates a structured review with inline comments as soon as a PR opens or updates.
|
||||
|
||||
**Features:**
|
||||
- Automatic code review on PR open/update
|
||||
- Inline comments on specific lines
|
||||
- Reviews for correctness, readability, testing, performance, DX
|
||||
|
||||
**Usage:**
|
||||
```bash
|
||||
# Copy the workflow file
|
||||
cp examples/github-actions/claude-pr-auto-review.yml .github/workflows/
|
||||
|
||||
# Open a PR - Claude will automatically review it
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 2. Security Review (`claude-security-review.yml`)
|
||||
|
||||
Runs a focused security scan and comments findings directly on the PR.
|
||||
|
||||
**Features:**
|
||||
- Security-focused analysis on every PR
|
||||
- Identifies potential vulnerabilities
|
||||
- OWASP Top 10 considerations
|
||||
- Posts findings as PR comments
|
||||
|
||||
**Configuration:**
|
||||
```yaml
|
||||
# Optional parameters in the workflow file:
|
||||
exclude-directories: "docs,examples" # Skip certain directories
|
||||
claudecode-timeout: "20" # Timeout in minutes
|
||||
claude-model: "claude-3-5-sonnet-20240620" # Model to use
|
||||
```
|
||||
|
||||
**Usage:**
|
||||
```bash
|
||||
# Copy the workflow file
|
||||
cp examples/github-actions/claude-security-review.yml .github/workflows/
|
||||
|
||||
# Every PR will be automatically scanned for security issues
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 3. Issue Triage (`claude-issue-triage.yml`)
|
||||
|
||||
When a new issue opens, Claude proposes labels/severity and posts a tidy triage comment.
|
||||
|
||||
**Features:**
|
||||
- Automatic issue classification
|
||||
- Label suggestions
|
||||
- Severity assessment (low, medium, high, critical)
|
||||
- Duplicate detection
|
||||
- Markdown triage comment
|
||||
|
||||
**Auto-apply Labels (Optional):**
|
||||
To automatically apply suggested labels, edit the workflow file and change:
|
||||
```yaml
|
||||
- name: Apply labels (optional)
|
||||
if: ${{ false }} # Change to true to auto-apply labels
|
||||
```
|
||||
|
||||
**Usage:**
|
||||
```bash
|
||||
# Copy the workflow file
|
||||
cp examples/github-actions/claude-issue-triage.yml .github/workflows/
|
||||
|
||||
# Open a new issue - Claude will automatically triage it
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Customization
|
||||
|
||||
### Model Selection
|
||||
Set `CLAUDE_MODEL` or `claude-model` parameter in workflows:
|
||||
```yaml
|
||||
env:
|
||||
CLAUDE_MODEL: claude-3-5-sonnet-20240620
|
||||
```
|
||||
|
||||
### Permissions
|
||||
Each workflow declares minimal required permissions:
|
||||
- `pull-requests: write` for PR reviews
|
||||
- `issues: write` for issue triage
|
||||
- `contents: read` for reading repository content
|
||||
|
||||
Adjust only if your organization requires stricter policies.
|
||||
|
||||
### Scope Filtering
|
||||
Use `paths:` filters to limit when workflows run:
|
||||
```yaml
|
||||
on:
|
||||
pull_request:
|
||||
paths:
|
||||
- 'src/**'
|
||||
- '!docs/**'
|
||||
```
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
**No comments appear on PRs:**
|
||||
- Verify the Claude GitHub App is installed
|
||||
- Check workflow has `pull-requests: write` permission
|
||||
|
||||
**403 when applying labels:**
|
||||
- Ensure the job has `issues: write` permission
|
||||
- Verify `GITHUB_TOKEN` has access to this repo
|
||||
|
||||
**Anthropic API errors:**
|
||||
- Confirm `ANTHROPIC_API_KEY` is set at repository level
|
||||
- Check the key is not expired
|
||||
|
||||
**YAML syntax errors:**
|
||||
- Validate spacing: two spaces per nesting level, no tabs
|
||||
- Use a YAML validator: [yamllint.com](https://www.yamllint.com/)
|
||||
|
||||
## Advanced Usage
|
||||
|
||||
### Combining Workflows
|
||||
Run multiple workflows together for comprehensive automation:
|
||||
- PR Review + Security Review on every PR
|
||||
- Issue Triage + Auto-labeling for new issues
|
||||
|
||||
### Custom Prompts
|
||||
Edit the `direct_prompt` section in workflows to customize Claude's focus:
|
||||
```yaml
|
||||
direct_prompt: |
|
||||
Review this PR focusing on:
|
||||
1. TypeScript type safety
|
||||
2. React performance patterns
|
||||
3. Accessibility compliance
|
||||
4. Test coverage
|
||||
```
|
||||
|
||||
### Integration with Other Actions
|
||||
Combine with existing workflows:
|
||||
```yaml
|
||||
jobs:
|
||||
tests:
|
||||
runs-on: ubuntu-latest
|
||||
steps:
|
||||
- name: Run tests
|
||||
run: npm test
|
||||
|
||||
claude-review:
|
||||
needs: tests # Run after tests pass
|
||||
runs-on: ubuntu-latest
|
||||
steps:
|
||||
- uses: anthropics/claude-code-action@main
|
||||
# ...
|
||||
```
|
||||
|
||||
## Cost Considerations
|
||||
|
||||
These workflows consume Anthropic API credits:
|
||||
- **PR Review**: ~$0.10-$0.50 per review (depending on diff size)
|
||||
- **Security Review**: ~$0.20-$0.80 per scan
|
||||
- **Issue Triage**: ~$0.05-$0.20 per issue
|
||||
|
||||
**Tips to reduce costs:**
|
||||
- Use `paths:` filters to skip docs/config changes
|
||||
- Set conditions: `if: github.event.pull_request.draft == false`
|
||||
- Review logs and adjust model selection
|
||||
|
||||
## Examples in This Directory
|
||||
|
||||
```
|
||||
examples/github-actions/
|
||||
├── README.md # This file
|
||||
├── claude-pr-auto-review.yml # Auto PR review workflow
|
||||
├── claude-security-review.yml # Security scanning workflow
|
||||
└── claude-issue-triage.yml # Issue triage workflow
|
||||
```
|
||||
|
||||
## Resources
|
||||
|
||||
- [Claude Code Documentation](https://claude.ai/code)
|
||||
- [GitHub Actions Documentation](https://docs.github.com/en/actions)
|
||||
- [Anthropic API Documentation](https://docs.anthropic.com/)
|
||||
- [Claude GitHub App](https://github.com/apps/claude)
|
||||
|
||||
## License
|
||||
|
||||
These workflows are provided as examples. Adapt them to your needs.
|
||||
Loading…
Add table
Add a link
Reference in a new issue