docs: add fork support documentation for PR review workflow

- Add comprehensive section on extending PR review workflow to support forks
- Document simple fork support approach using contributor's own Google auth
- Explain GitHub Actions security model for fork-based PRs
- Provide implementation approaches from simple to advanced
- Include security best practices and resources for pull_request_target
- Reference centralized authentication documentation
- Reorganize content with clear implementation approaches

Author: jerop

examples/workflows/pr-review/README.md

@@ -28,6 +28,11 @@ This document explains how to use the Gemini CLI on GitHub to automatically revi
     - [Security-Focused Review](#security-focused-review)
     - [Performance Review](#performance-review)
     - [Breaking Changes Check](#breaking-changes-check)
+  - [Extending to Support Forks](#extending-to-support-forks)
+    - [Understanding Fork Security Model](#understanding-fork-security-model)
+    - [Implementation Approaches](#implementation-approaches)
+      - [1. Simple Fork Support (Recommended for Open Source)](#1-simple-fork-support-recommended-for-open-source)
+      - [2. Using `pull_request_target` Event](#2-using-pull_request_target-event)
 
 ## Overview
 
@@ -237,3 +242,102 @@ The AI prompt can be customized to:
 ```
 @gemini-cli /review look for potential breaking changes and API compatibility
 ```
+
+## Extending to Support Forks
+
+By default, this workflow is configured to work with pull requests from branches
+within the same repository. The
+[gemini-dispatch.yml](../gemini-dispatch/gemini-dispatch.yml) workflow includes
+a condition that explicitly blocks pull requests from forks:
+
+```yaml
+github.event.pull_request.head.repo.fork == false
+```
+
+However, if you want to extend it to support pull requests from forked
+repositories, there are several approaches depending on your authentication
+setup and security requirements.
+
+### Understanding Fork Security Model
+
+When pull requests come from forks, GitHub Actions restricts access to secrets
+and repository tokens to prevent malicious code from accessing sensitive
+information. However, the impact depends on what secrets are actually needed:
+
+- **Available from forks**: `GITHUB_TOKEN` (with limited permissions),
+  repository content, pull request data.
+- **Restricted from forks**: Base repository secrets and authentication.
+- **Workaround**: Forks can configure their own Google authentication as
+  described in the
+  [Authentication documentation](../../../docs/authentication.md).
+
+### Implementation Approaches
+
+Depending on your security requirements and use case, you can choose from these
+approaches:
+
+#### 1. Simple Fork Support (Recommended for Open Source)
+
+**Best for**: Open source projects where contributors can provide their own
+Google authentication.
+
+**How it works**: If forks have their own Google authentication configured, you
+can enable fork support by simply removing the fork restriction condition in the
+dispatch workflow. This works because:
+
+- **Gemini access**: The workflow can use the fork's Google authentication (see
+  [Authentication documentation](../../../docs/authentication.md)).
+- **GitHub access**: GitHub provides a default `GITHUB_TOKEN` with read access
+  to the repository and write access to pull requests.
+
+**Requirements**: 
+- Fork repositories must have Google authentication configured (see
+  [Authentication documentation](../../../docs/authentication.md)).
+- Contributors are willing to use their own Gemini API quota.
+
+**Implementation**:
+1. Remove the fork restriction in `gemini-dispatch.yml`:
+   ```yaml
+   # Change this condition to remove the fork check
+   if: |-
+     (
+       github.event_name == 'pull_request'
+       # Remove this line: && github.event.pull_request.head.repo.fork == false
+     ) || (
+       # ... rest of conditions
+     )
+   ```
+
+2. Document for contributors that they need to configure Google authentication
+   in their fork as described in the
+   [Authentication documentation](../../../docs/authentication.md).
+
+**Benefits**: Simple, secure, no access to base repository secrets.
+**Drawbacks**: Requires contributors to configure their own authentication.
+
+#### 2. Using `pull_request_target` Event
+
+**Important Security Note**: Using `pull_request_target` can introduce security
+vulnerabilities if not handled with extreme care. Because it runs in the context
+of the base repository, it has access to secrets and other sensitive data.
+Always ensure you are following security best practices, such as those outlined
+in the linked resources, to prevent unauthorized access or code execution.
+
+**Best for**: Private repositories where you want to provide API access centrally.
+
+Modify the workflow to use `pull_request_target` instead of `pull_request`,
+which runs with the base repository's permissions:
+
+- **Benefits**: Full access to base repository secrets and permissions.
+- **Security Considerations**: Requires careful code review and validation of
+  all fork contributions.
+- **Resources**:
+  - [GitHub Docs: Using pull_request_target](https://docs.github.com/en/actions/using-workflows/events-that-trigger-workflows#pull_request_target).
+  - [Security Best Practices for pull_request_target](https://securitylab.github.com/research/github-actions-preventing-pwn-requests/).
+  - [Safe Workflows for Forked Repositories](https://github.blog/2020-08-03-github-actions-improvements-for-fork-and-pull-request-workflows/).
+- **Best Practices**:
+  - Never execute untrusted code from forks without proper sandboxing.
+  - Validate all inputs from external pull requests.
+  - Review workflow changes carefully before implementing `pull_request_target`.
+  - Test security measures in a separate repository first.
+  - Monitor and audit fork-based workflow executions.