Add two-stage workflow for secure Claude reviews on forked PRs

[Wirasm]

Pull Request

Summary

Implements a secure two-stage workflow system to enable Claude Code reviews on pull requests from forked repositories, addressing the GitHub Actions security limitation where forked PRs cannot access repository secrets.

Changes Made

• Created Stage 1 workflow (claude-review-ext-stage1.yml) to collect PR information without secrets
• Created Stage 2 workflow (claude-review-ext.yml) to perform secure Claude review with secrets access
• Added comprehensive documentation explaining the security model and usage
• Implemented @claude-review-ext trigger command for external PR reviews

Type of Change

• New feature (non-breaking change which adds functionality)
• Bug fix (non-breaking change which fixes an issue)
• Breaking change (fix or feature that would cause existing functionality to not work as expected)
• Documentation update
• Performance improvement
• Code refactoring

Affected Services

• Frontend (React UI)
• Server (FastAPI backend)
• MCP Server (Model Context Protocol)
• Agents (PydanticAI service)
• Database (migrations/schema)
• Docker/Infrastructure
• Documentation site

Testing

• All existing tests pass
• Added new tests for new functionality
• Manually tested affected user flows
• Docker builds succeed for all services

Test Evidence

# Validated YAML syntax for both workflow files
# Workflows will be tested on actual forked PRs after merge

Checklist

• My code follows the service architecture patterns
• If using an AI coding assistant, I used the CLAUDE.md rules
• I have added tests that prove my fix/feature works
• All new and existing tests pass locally
• My changes generate no new warnings
• I have updated relevant documentation
• I have verified no regressions in existing features

Breaking Changes

None - this adds new functionality without modifying existing workflows.

Additional Notes

Security Model

The two-stage approach maintains GitHub's security model:

• Stage 1: Runs on fork code but has no secrets access (safe)
• Stage 2: Has secrets access but never checks out fork code (secure)

How It Works

1. External contributor submits PR from fork
2. Stage 1 workflow collects PR information and uploads as artifact
3. Stage 2 workflow downloads artifact and runs Claude review in secure context
4. Review is posted as PR comment

Usage

• Trigger command: @claude-review-ext
• Authorized users: Wirasm, coleam00, sean-eskerium
• Works alongside existing @claude-review for direct branches

Key Security Features

• No direct execution of untrusted fork code with secrets
• Artifact-based communication between stages
• Authorization checks for manual triggers
• Reviews changes via git diff, not code execution

This solution addresses the limitation where @claude-review works for maintainers but not for external contributors from forks.

[Wirasm]

@claude-review

[claude]

Claude finished @Wirasm's task —— View job

---

Claude Code Review

Todo List:

• Read and analyze documentation file
• Review Stage 1 workflow implementation
• Review Stage 2 workflow implementation
• Evaluate security model and implementation
• Check workflow syntax and GitHub Actions best practices
• Provide comprehensive review feedback

Summary

Implements a sophisticated two-stage workflow system that enables secure Claude Code reviews on external PRs from forks by separating PR information collection (Stage 1, no secrets) from the actual review execution (Stage 2, with secrets). The implementation correctly addresses GitHub Actions' security limitations while maintaining review functionality.

Previous Review Comments

First review - no previous comments

Issues Found

Total: 0 critical, 2 important, 3 minor

🔴 Critical (Must Fix)

None found.

🟡 Important (Should Fix)

• Stage 1 Checkout Security - .github/workflows/claude-review-ext-stage1.yml:35-38
  Problem: Stage 1 checks out PR code (actions/checkout@v4 with default behavior) which executes in the fork's context but still has read access to the main repo
  Fix: Consider adding explicit token: ${{ secrets.GITHUB_TOKEN }} and document that this is acceptable since no secrets are available in Stage 1

• Hard-coded Base Branch Reference - .github/workflows/claude-review-ext.yml:129
  Problem: Uses ${{ github.event.workflow_run.head_branch }} to checkout, but this refers to the trigger workflow's branch, not necessarily the target base branch
  Fix: Should fetch the base branch from PR info: ref: ${{ github.event.repository.default_branch }} or extract from PR data

🟢 Minor (Consider)

• Artifact Retention - .github/workflows/claude-review-ext-stage1.yml:194
  Suggestion: 1-day retention is very short; consider 3-7 days for debugging failed reviews

• Error Handling Enhancement - .github/workflows/claude-review-ext.yml:72
  Suggestion: Add error handling for malformed pr-info.json files with jq -e checks before processing

• Documentation Completeness - .github/workflows/README-EXTERNAL-PRS.md:137
  Suggestion: Add artifact size limits section (GitHub has ~500MB limit per artifact)

Security Assessment

Excellent security model implementation. Key security features verified:

✅ Two-stage isolation: Stage 1 has no secrets, Stage 2 never executes PR code
✅ Proper permissions: Each stage has minimal required permissions
✅ Authorization checks: Only authorized users can trigger manual reviews
✅ Artifact-based communication: No direct code execution in Stage 2
✅ Base branch checkout: Stage 2 safely analyzes diffs without running PR code
✅ No secrets exposure: PR information collection happens without secret access

The implementation follows GitHub's security best practices for handling untrusted fork PRs.

Performance Considerations

• Workflow chaining delay: Expected 30-60 second delay between stages due to workflow_run trigger
• Artifact download overhead: Acceptable for JSON payload sizes
• Diff analysis efficiency: Git diff approach is optimal for large PRs
• Timeout handling: 15-minute timeout is appropriate for Claude API calls

No performance concerns identified.

Good Practices Observed

• Comprehensive documentation with clear security model explanation and troubleshooting guide
• Excellent error messaging with detailed job summaries and status comments
• Proper YAML structure with clear comments explaining security considerations
• Event filtering logic correctly handles different trigger scenarios (PR events vs comments)
• Authorization model with explicit user allowlisting
• Fallback handling with unauthorized user messaging
• Artifact naming with PR number for easy identification

Questionable Practices

• Duplicate artifact download code between authorization check and main review job could be extracted to a reusable action
• Manual user list maintenance in YAML could become outdated (consider GitHub teams)

Test Coverage

Current Coverage: Documentation and workflow configuration only

Missing Tests:
Since these are GitHub Actions workflows, traditional unit testing isn't applicable. However, consider:

1. Integration Testing

   • What to test: End-to-end workflow execution with test PRs
   • Why important: Validates the complete two-stage process
   • Suggested test: Create test fork PR and verify review posting

2. Security Validation

   • What to test: Unauthorized user attempts and malicious PR handling
   • Why important: Ensures security model holds under attack
   • Suggested test: Test with non-authorized user triggering review

Recommendations

Merge Decision:

• Ready to merge as-is

Priority Actions:

1. Consider fixing the base branch checkout issue in Stage 2 (line 129)
2. Document artifact size limitations for very large PRs

Rationale:
This is an excellent implementation of a secure two-stage review system. The security model is sound, the code quality is high, and the documentation is comprehensive. The identified issues are minor and don't affect core functionality. The implementation correctly solves the challenging problem of enabling Claude reviews on fork PRs while maintaining GitHub's security guarantees.

The approach is well-architected for an alpha project, focusing on functionality while maintaining security best practices. The comprehensive documentation will help maintainers and contributors understand the system.

---

Review based on Archon V2 Alpha guidelines and CLAUDE.md principles