Add Claude Code GitHub Workflow

[mathaix]

🤖 Installing Claude Code GitHub App

This PR adds a GitHub Actions workflow that enables Claude Code integration in our repository.

What is Claude Code?

Claude Code is an AI coding agent that can help with:

• Bug fixes and improvements
• Documentation updates
• Implementing new features
• Code reviews and suggestions
• Writing tests
• And more!

How it works

Once this PR is merged, we'll be able to interact with Claude by mentioning @claude in a pull request or issue comment.
Once the workflow is triggered, Claude will analyze the comment and surrounding context, and execute on the request in a GitHub action.

Important Notes

• This workflow won't take effect until this PR is merged
• @claude mentions won't work until after the merge is complete
• The workflow runs automatically whenever Claude is mentioned in PR or issue comments
• Claude gets access to the entire PR or issue context including files, diffs, and previous comments

Security

• Our Anthropic API key is securely stored as a GitHub Actions secret
• Only users with write access to the repository can trigger the workflow
• All Claude runs are stored in the GitHub Actions run history
• Claude's default tools are limited to reading/writing files and interacting with our repo by creating comments, branches, and commits.
• We can add more allowed tools by adding them to the workflow file like:

allowed_tools: Bash(npm install),Bash(npm run build),Bash(npm run lint),Bash(npm run test)

There's more information in the Claude Code action repo.

After merging this PR, let's try mentioning @claude in a comment on any PR to get started!

[claude]

Code Review: Claude Code GitHub Workflow Integration

Thank you for setting up Claude Code integration! This is a well-structured PR that adds both automatic code review and on-demand assistance capabilities. Here's my detailed review:

---

✅ Overall Assessment

LGTM with suggestions - The workflows are well-configured and follow GitHub Actions best practices. I've identified a few areas for improvement below.

---

🔒 Security Considerations

HIGH PRIORITY:

1. Missing write permissions for automated reviews (claude-code-review.yml:22-26)

   • The workflow can read PRs but cannot post comments
   • Current permissions: pull-requests: read
   • Required: pull-requests: write to enable gh pr comment
   • Without this, the automated review will fail when attempting to post feedback

2. Workflow write access needed (claude.yml:21-26)

   • The main Claude workflow also lacks write permissions
   • Add: pull-requests: write, issues: write, contents: write
   • These are needed for Claude to create comments, branches, and commits as described in the PR description

MEDIUM PRIORITY:

3. Secret protection (both files)
   • ✅ Good: Using CLAUDE_CODE_OAUTH_TOKEN secret
   • ⚠️ Consider: Adding repository-level branch protection to prevent unauthorized workflow modifications
   • ⚠️ Consider: Restricting which actors can trigger workflows using if conditions

---

🐛 Potential Bugs

1. Silent failure on permissions (claude-code-review.yml:52)

   • The workflow will complete successfully even if gh pr comment fails due to missing permissions
   • Suggestion: Add error handling or permission checks

2. No shallow clone limitations documented (both files, line 31-32)

   • Using fetch-depth: 1 is efficient but limits git history access
   • For security-sensitive projects, Claude may need deeper history to understand context
   • Consider: fetch-depth: 0 or document this limitation

---

🎯 Best Practices & Code Quality

Strengths:

• ✅ Clear separation of concerns (auto-review vs. on-demand)
• ✅ Using latest checkout action (@v4)
• ✅ Minimal permissions (good security posture, just needs updates)
• ✅ Excellent documentation in PR body

Suggestions:

1. Path filtering inconsistency (claude-code-review.yml:6-11)

   • Commented-out path filters only include TypeScript/JavaScript
   • Your project uses Python (FastAPI) and TypeScript
   • Add Python patterns when enabling:

   paths:
     - "src/**/*.py"
     - "src/**/*.ts"
     - "src/**/*.tsx"

2. Missing allowed tools for full functionality (claude.yml:49)

   • The main workflow has commented-out claude_args
   • Without allowed tools, Claude cannot run tests, builds, or make commits
   • Recommended based on CLAUDE.md:

   claude_args: '--allowed-tools "Bash(uv:*),Bash(pytest:*),Bash(pnpm:*),Bash(gh:*),Bash(git:*),Bash(docker-compose:*)"'

3. No timeout protection (both files)

   • Workflows could run indefinitely on complex PRs
   • Add: timeout-minutes: 30 to job definitions

4. Environment-specific considerations (claude-code-review.yml:39-52)

   • The prompt doesn't mention Clara's specific tech stack
   • Enhancement: Reference SECURITY-GOVERNANCE.md for security reviews

---

⚡ Performance Considerations

1. Resource usage (both files)

   • Every PR triggers automatic review (potentially expensive)
   • Consider: Enable path filtering or author filtering to reduce runs
   • Cost estimate: With current setup, expect ~1 review per PR at API costs

2. Concurrent workflow runs

   • Multiple PR updates (synchronize events) could trigger parallel reviews
   • Add concurrency controls to prevent redundant runs

---

🧪 Test Coverage

Missing:

• No validation that the workflow actually works with correct permissions
• Recommendation: After merging, create a test PR to verify:
  1. Automated review posts successfully
  2. @claude mentions work in comments
  3. Allowed tools are accessible

---

📋 Suggested Changes Summary

Must fix before merge:

1. Add pull-requests: write to claude-code-review.yml:24
2. Add write permissions to claude.yml:22-26:
   • contents: write
   • pull-requests: write
   • issues: write

Should consider:

1. Add timeout limits to both workflows
2. Add concurrency controls to prevent redundant runs
3. Expand allowed tools in claude.yml for full functionality
4. Update review prompt to reference Clara-specific security requirements

Nice to have:

1. Path filtering for Python files
2. Branch protection rules for workflow security

---

📖 Documentation

The PR description is excellent! Small addition suggestion:

Post-Merge Checklist:

• Verify CLAUDE_CODE_OAUTH_TOKEN secret is configured
• Test automated review on a new PR
• Test @claude mention in issue comment
• Review Actions logs for any permission errors

---

Final Verdict

This is a solid foundation for Claude Code integration. The workflows are well-structured and the security approach is conservative (read-only by default). However, the missing write permissions will prevent the workflows from functioning as intended.

Recommended action: Update permissions as noted above, then merge with confidence.

Great work on the clear documentation and thoughtful setup! 🚀