Add Claude Code GitHub Workflow

[jxnl]

🤖 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!

---

Important

Adds GitHub Actions workflows for Claude Code integration, enabling automated code reviews and handling @claude mentions in comments and issues.

• Workflows:
  • Adds claude-code-review.yml to automate code reviews on PR events (opened, synchronize).
  • Adds claude.yml to trigger Claude on issue_comment, pull_request_review_comment, issues, and pull_request_review events when @claude is mentioned.
• Security & Permissions:
  • Uses claude_code_oauth_token stored as a GitHub Actions secret for authentication.
  • Grants read permissions for contents, pull-requests, issues, and write for id-token.
  • Allows Claude to read CI results on PRs with actions: read permission.
• Customization:
  • Supports optional configurations like model selection, trigger phrases, and allowed tools.
  • Provides direct prompts for automated reviews and allows sticky comments for persistent feedback.

^{This description was created by for 9160d1a. You can customize this summary. It will automatically update as commits are pushed.}

[claude]

Claude finished @jxnl's task —— View job • claude/pr-1688-20250710_153511 • [Create PR ➔](https://github.com/567-labs/instructor/compare/main...claude/pr-1688-20250710_153511?quick_pull=1&title=PR%20%231688%3A%20Changes%20from%20Claude&body=This%20PR%20addresses%20pr%20%231688%0A%0AGenerated%20with%20%5BClaude%20Code%5D(https%3A%2F%2Fclaude.ai%2Fcode)

---

Code Review: Claude Code GitHub Workflow Integration

Overall Assessment

This PR successfully integrates Claude Code into the instructor repository with two complementary workflows:

1. claude-code-review.yml (New Automated Review Workflow)

✅ Strengths

• Well-structured: Clear workflow definition with proper triggers on PR events
• Comprehensive review prompt: Covers code quality, bugs, performance, security, and test coverage
• Extensive documentation: Excellent inline comments showing various configuration options
• Flexible configuration: Multiple commented examples for different use cases

⚠️ Areas for Improvement

• Outdated checkout action: Uses actions/checkout@v4 while existing workflows use @v2 (line 30)
• Minimal fetch depth: fetch-depth: 1 may limit Claude's ability to analyze context across commits
• No conditional logic: Unlike other workflows, this runs on all PRs without filtering

🔧 Recommendations

1. Consistency: Consider aligning with existing workflow patterns (checkout version, formatting)
2. Selective triggering: Consider adding path filters or PR size limits to avoid unnecessary runs
3. Resource optimization: Add conditions to skip trivial changes (docs-only, version bumps)

2. claude.yml (Enhanced Interactive Workflow)

✅ Strengths

• Comprehensive trigger coverage: Handles multiple GitHub events (issues, comments, reviews)
• Proper permissions: Includes required actions: read permission for CI result access
• Flexible configuration: Good examples of optional settings
• Security-conscious: Uses secrets properly for API token

⚠️ Areas for Improvement

• Version inconsistency: Uses actions/checkout@v4 while other workflows use @v2
• Complex conditional logic: The if condition is quite long and could be more readable

🔧 Recommendations

1. Simplify conditionals: Consider extracting the trigger logic into a reusable function
2. Version alignment: Standardize checkout action version across all workflows

3. Security Assessment

✅ Secure Practices

• Secret management: Properly uses GitHub secrets for API tokens
• Minimal permissions: Only requests necessary permissions
• Limited scope: Workflows are properly scoped to required resources

⚠️ Security Considerations

• External action dependency: Relies on anthropics/claude-code-action@beta (beta version)
• No verification: No SHA pinning or checksum verification for external actions
• Broad trigger scope: Automated review runs on all PRs without size/complexity filtering

4. Performance Considerations

✅ Efficient Design

• Parallel execution: Two workflows can run independently
• Event-driven: Only triggers when needed
• Resource-conscious: Uses ubuntu-latest runners

⚠️ Performance Concerns

• Potential overuse: Automated reviews on every PR could consume significant API quota
• No caching: Unlike other workflows, these don't leverage caching mechanisms
• Beta dependency: Using beta version may have performance or reliability issues

5. Test Coverage & Quality

⚠️ Missing Elements

• No integration tests: No tests for the workflow configurations themselves
• No validation: No checks for workflow syntax or configuration validity
• No monitoring: No metrics or alerts for workflow failures

6. Code Quality & Best Practices

✅ Good Practices

• Clear naming: Descriptive workflow and job names
• Documentation: Extensive inline comments explaining options
• Modular design: Separate workflows for different use cases

⚠️ Inconsistencies

• Action versions: Inconsistent with existing workflows (@v4 vs @v2)
• Formatting: Different indentation and spacing patterns
• Structure: Different organization compared to existing workflows

Summary

The implementation successfully adds Claude Code integration with thoughtful design and extensive configuration options. The main areas for improvement are:

1. Consistency: Align with existing workflow patterns and versions
2. Resource optimization: Add filtering to prevent unnecessary runs
3. Security: Consider pinning external action versions
4. Testing: Add validation for workflow configurations

The code is production-ready but would benefit from the suggested improvements for better integration with the existing codebase standards.

Risk Level: Low - The changes are well-implemented with proper security practices
Recommendation: Approve with minor improvements suggested above

[ellipsis-dev]

Important

Looks good to me! 👍

Reviewed everything up to 9160d1a in 1 minute and 24 seconds. Click for details.

• Reviewed 142 lines of code in 2 files
• Skipped 0 files when reviewing.
• Skipped posting 3 draft comments. View those below.
• Modify your settings and rules to customize what types of comments Ellipsis leaves. And don't forget to react with 👍 or 👎 to teach Ellipsis.

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

• Draft comment:
  Consider removing or enabling the commented-out PR author filter (lines 15-19) to reduce clutter.
• Reason this comment was not posted:
  Confidence changes required: 33% <= threshold 85% None

2. .github/workflows/claude.yml:37

• Draft comment:
  Token secret updated to 'claude_code_oauth_token'; ensure documentation and integrations reference this change.
• Reason this comment was not posted:
  Comment looked like it was already resolved.

3. .github/workflows/claude.yml:26

• Draft comment:
  A brief comment explaining the 'actions: read' permission (for accessing CI results) would aid future maintainers.
• Reason this comment was not posted:
  Confidence changes required: 50% <= threshold 85% None

Workflow ID: wflow_WJbk1Iz67OIfYHW7

^{You can customize by changing your verbosity settings, reacting with 👍 or 👎, replying to comments, or adding code review rules.}