Add Claude Code GitHub Workflow

[akshayutture-augment]

🤖 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 - PR #75: Add Claude Code GitHub Workflow

Thank you for adding Claude Code integration to Keycloak! I've reviewed the workflow files and have the following feedback:

✅ Positive Aspects

1. Clear Documentation: The PR description provides excellent documentation about what Claude Code is and how it works
2. Security Conscious: Good use of GitHub secrets for API key storage
3. Appropriate Permissions: The workflows use minimal, scoped permissions following the principle of least privilege
4. Dual Workflow Approach: Smart separation between automated code review (claude-code-review.yml) and on-demand assistance (claude.yml)

🔍 Code Quality & Best Practices

Workflow Configuration

.github/workflows/claude-code-review.yml:

• ✅ Uses actions/checkout@v4 with minimal fetch-depth: 1 - efficient
• ✅ Properly scoped permissions (contents: read, pull-requests: read, issues: read, id-token: write)
• ✅ Uses anthropics/claude-code-action@v1 - good to specify version
• ⚠️ Recommendation: Consider pinning to a specific commit SHA instead of @v1 for better security and reproducibility, similar to how other workflows in this repo use commit SHAs (e.g., actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683)

.github/workflows/claude.yml:

• ✅ Comprehensive trigger conditions for @claude mentions
• ✅ Proper conditional logic with if statement
• ✅ Includes actions: read permission for Claude to access CI results
• ⚠️ Recommendation: Same as above - pin action versions to commit SHAs

🐛 Potential Issues

1. Missing Permissions for PR Comments: The claude-code-review.yml workflow needs pull-requests: write permission to post comments on PRs. Currently it only has pull-requests: read.

   Fix needed in .github/workflows/claude-code-review.yml:

   permissions:
     contents: read
     pull-requests: write  # Changed from 'read' to 'write'
     issues: read
     id-token: write

2. Incomplete Workflow Integration: The claude.yml workflow is missing pull-requests: write permission if Claude needs to create comments, commits, or branches.

   Consider adding:

   permissions:
     contents: write  # For creating commits
     pull-requests: write  # For commenting
     issues: write  # For commenting on issues
     id-token: write
     actions: read

🚀 Performance Considerations

1. Trigger Frequency: The claude-code-review.yml runs on every PR open/synchronize. For a large repository like Keycloak:

   • Consider adding path filters to only run on specific file changes
   • Consider adding author filters (currently commented out) to limit to specific contributors
   • This will help manage API costs and CI resources

2. Fetch Depth: Both workflows use fetch-depth: 1 which is optimal for performance ✅

🔒 Security Concerns

1. API Key Protection: ✅ Good use of secrets.ANTHROPIC_API_KEY

2. Action Version Pinning: ⚠️ As noted above, this repo follows a pattern of pinning actions to specific commit SHAs (see ci.yml:45, codeql-analysis.yml:40). This should be applied to the Claude action as well:

   uses: anthropics/claude-code-action@<commit-sha>  # v1

3. Limited Tool Access: ✅ The claude-code-review.yml properly restricts Claude to only read-only gh commands for viewing PRs. Good security practice!

4. Write Access Controls: The commented-out author filters in claude-code-review.yml are a good security feature to consider enabling, especially for automatic reviews

🧪 Test Coverage

⚠️ Missing: No tests or validation for the workflows themselves. Consider:

• Testing the workflow in a fork or separate branch before merging
• Verifying the ANTHROPIC_API_KEY secret is properly configured
• Running a test invocation after merge to ensure everything works

📋 Alignment with Repository Standards

Based on CONTRIBUTING.md and PR-CHECKLIST.md:

1. ✅ PR follows the format of other workflows in the repository
2. ⚠️ Missing: GitHub Issue link - The CONTRIBUTING.md states "Each PR, no matter how small, should have a GitHub issue associated with it"
3. ⚠️ Question: Should this include documentation updates to inform contributors about the new @claude feature? Consider updating CONTRIBUTING.md or README.md
4. ⚠️ Style inconsistency: Other workflows in this repo pin actions to commit SHAs, this one uses @v1

📝 Recommendations Summary

Required Changes:

1. Add pull-requests: write permission to claude-code-review.yml
2. Update permissions in claude.yml to include write access for Claude's operations
3. Pin action versions to commit SHAs for security consistency

Recommended Enhancements:

1. Add path filters to claude-code-review.yml to reduce unnecessary runs
2. Create a GitHub issue and link it in the PR description/commit message
3. Consider updating documentation to explain the @claude feature to contributors
4. Test the workflow in a safe environment before deploying to production

Overall Assessment

This is a valuable addition to the repository that will enhance developer productivity. The implementation is well-structured with good separation of concerns. The main issues are around permissions and consistency with repository standards. Once the permissions are corrected, this should work well.

Suggested Priority: Address the permissions issues before merging, as the workflows won't function correctly without write permissions.