Add comprehensive fork PR support documentation and examples

[keithah]

This PR addresses multiple open issues related to fork PR support:

• Fixes Claude review fails on PRs from forks #339 - Claude review fails on PRs from forks
• Fixes Could not fetch an OIDC token when attempting to execute on a branch from a fork #542 - OIDC token errors on fork PRs
• Fixes Claude Code Action fails with "couldn't find remote ref" error for PRs from forks #223 - "couldn't find remote ref" errors for fork PRs
• Fixes Comments in (forked) PR trigger claude-code-action with wrong branch #46 - Wrong branch checkout for forked PRs

Summary

Fork PRs have been a persistent pain point for users. This PR provides comprehensive documentation and updated examples to make fork PR support work seamlessly for both @claude mentions and automated reviews.

Changes

📚 Documentation

New: docs/fork-pr-support.md

Comprehensive guide covering:

• Two scenarios: @claude mentions vs automated reviews
• Step-by-step solutions with clear explanations of why each fix works
• Security considerations for pull_request_target
• Complete working examples
• Troubleshooting guide for common errors
• Migration instructions for existing workflows
• Comparison table: pull_request vs pull_request_target

Updated: docs/faq.md

• Added "Fork Pull Requests" section
• Common fork PR errors and solutions
• Links to detailed fork PR support guide
• Updated best practices

🔧 Example Workflows

All PR review examples updated to support fork PRs:

examples/claude.yml (@claude mentions)

• Added fork detection step using GitHub API
• Dynamically checkouts fork repository when needed
• Works seamlessly for both fork and non-fork PRs

examples/pr-review-*.yml (Automated reviews)

Updated all three PR review examples:

• Changed to pull_request_target trigger
• Checkout fork repository correctly
• Added github_token to bypass OIDC issues
• Added allowed_non_write_users: '*' to allow fork contributors
• Added security notes referencing fork PR documentation

Key Technical Fixes

Fix 1: @claude Mentions on Fork PRs

Problem: Fork branches don't exist in base repository

Solution: Detect fork PRs and checkout fork repository directly

- name: Get PR info for fork support
  run: |
    PR_DATA=$(gh api repos/${{ github.repository }}/pulls/${{ github.event.issue.number }})
    # Extract fork info...

- uses: actions/checkout@v4
  with:
    repository: ${{ steps.pr-info.outputs.is_fork == 'true' && format('{0}/{1}', ...) || github.repository }}

Fix 2: Automated Reviews on Fork PRs

Problems:

1. Branch not found (same as above)
2. OIDC authentication fails with pull_request_target
3. Fork contributors lack write permissions

Solution: Apply three fixes

on:
  pull_request_target:  # Required for fork write access

steps:
  - uses: actions/checkout@v4
    with:
      repository: ${{ github.event.pull_request.head.repo.full_name }}  # Fix 1
      ref: ${{ github.event.pull_request.head.ref }}

  - uses: anthropics/claude-code-action@v1
    with:
      github_token: ${{ secrets.GITHUB_TOKEN }}      # Fix 2: Bypass OIDC
      allowed_non_write_users: '*'                    # Fix 3: Allow fork contributors

Security Analysis

Using allowed_non_write_users: '*' is safe for review workflows because:

• ✅ Reviews only read code and post comments (no code execution)
• ✅ Uses pull_request_target (runs in base repo context, not fork)
• ✅ No deployment or build steps with untrusted code
• ✅ Standard pattern for PR review automation

The documentation clearly explains when this is safe vs unsafe.

Testing

Successfully tested on xbmc/xbmc repository:

• ✅ @claude mentions working on fork PRs (PR #27089)
• ✅ Automated reviews working on fork PRs from users without write access (PR #27339)
• ✅ All three fixes verified working in production

Credits

Special thanks to @CryptoGnome whose aster_lick_hunter_node repository provided valuable insights for the fork repository checkout solution.

Migration Path

Users with existing workflows can follow the migration guide in docs/fork-pr-support.md to add fork support. The changes are backward compatible - non-fork PRs continue to work as before.

---

This should significantly improve the fork PR experience and close several long-standing issues! 🎉

[jrgilman]

Any news on this?