refactor: Use composite GitHub Action for PR review workflow

.github/workflows/pr-review-by-openhands.yml

@@ -38,8 +38,10 @@ jobs:
             cancel-in-progress: true
         runs-on: ubuntu-24.04
         env:
-            LLM_MODEL: litellm_proxy/claude-sonnet-4-5-20250929
-            LLM_BASE_URL: https://llm-proxy.app.all-hands.dev
+            LLM_MODEL: anthropic/claude-sonnet-4-5-20250929
+            # Review mode: 'cloud' launches the review in OpenHands Cloud
+            # This allows the review to run asynchronously without blocking CI
+            REVIEW_MODE: cloud
             # PR context will be automatically provided by the agent script
             PR_NUMBER: ${{ github.event.pull_request.number }}
             PR_TITLE: ${{ github.event.pull_request.title }}
@@ -84,30 +86,35 @@ jobs:
 
             - name: Install OpenHands dependencies
               run: |
-                  # Install OpenHands SDK and tools from local checkout
-                  uv pip install --system ./software-agent-sdk/openhands-sdk ./software-agent-sdk/openhands-tools
+                  # Install OpenHands SDK, tools, and workspace from local checkout
+                  uv pip install --system ./software-agent-sdk/openhands-sdk ./software-agent-sdk/openhands-tools ./software-agent-sdk/openhands-workspace
 
             - name: Check required configuration
               env:
                   LLM_API_KEY: ${{ secrets.LLM_API_KEY }}
+                  OPENHANDS_CLOUD_API_KEY: ${{ secrets.OPENHANDS_CLOUD_API_KEY }}
               run: |
                   if [ -z "$LLM_API_KEY" ]; then
                     echo "Error: LLM_API_KEY secret is not set."
                     exit 1
                   fi
 
+                  if [ "$REVIEW_MODE" = "cloud" ] && [ -z "$OPENHANDS_CLOUD_API_KEY" ]; then
+                    echo "Error: OPENHANDS_CLOUD_API_KEY secret is required for 'cloud' mode."
+                    exit 1
+                  fi
+
                   echo "PR Number: $PR_NUMBER"
                   echo "PR Title: $PR_TITLE"
                   echo "Repository: $REPO_NAME"
                   echo "LLM model: $LLM_MODEL"
-                  if [ -n "$LLM_BASE_URL" ]; then
-                    echo "LLM base URL: $LLM_BASE_URL"
-                  fi
+                  echo "Review mode: $REVIEW_MODE"
 
             - name: Run PR review
               env:
                   LLM_API_KEY: ${{ secrets.LLM_API_KEY }}
                   GITHUB_TOKEN: ${{ secrets.ALLHANDS_BOT_GITHUB_PAT }}
+                  OPENHANDS_CLOUD_API_KEY: ${{ secrets.OPENHANDS_CLOUD_API_KEY }}
               run: |
                   # Change to the PR repository directory so agent can analyze the code
                   cd pr-repo

examples/03_github_workflows/02_pr_review/README.md

@@ -14,6 +14,9 @@ This example demonstrates how to set up a GitHub Actions workflow for automated
 - **Automatic Trigger**: Reviews are triggered when:
   - The `review-this` label is added to a PR, OR
   - openhands-agent is requested as a reviewer
+- **Two Review Modes**:
+  - **SDK Mode** (`REVIEW_MODE=sdk`): Runs the agent locally in the GitHub Actions runner. The review completes within the CI job.
+  - **Cloud Mode** (`REVIEW_MODE=cloud`): Launches the review in [OpenHands Cloud](https://app.all-hands.dev). The CI job posts a comment with a link to track progress and exits immediately, allowing the review to run asynchronously.
 - **Inline Review Comments**: Posts review comments directly on specific lines of code in the PR diff, rather than a single giant comment. This makes it easier to:
   - See exactly which lines the feedback refers to
   - Address issues one by one
@@ -49,6 +52,8 @@ Set the following secrets in your GitHub repository settings:
 
 - **`LLM_API_KEY`** (required): Your LLM API key
   - Get one from the [OpenHands LLM Provider](https://docs.all-hands.dev/openhands/usage/llms/openhands-llms)
+- **`OPENHANDS_CLOUD_API_KEY`** (required for cloud mode): Your OpenHands Cloud API key
+  - Get one from [OpenHands Cloud Settings](https://app.all-hands.dev/settings/api-keys)
 
 **Note**: The workflow automatically uses the `GITHUB_TOKEN` secret that's available in all GitHub Actions workflows.
 
@@ -59,13 +64,17 @@ Edit `.github/workflows/pr-review-by-openhands.yml` to customize the configurati
 ```yaml
 env:
     # Optional: Use a different LLM model
-    LLM_MODEL: openhands/claude-sonnet-4-5-20250929
+    LLM_MODEL: anthropic/claude-sonnet-4-5-20250929
     # Optional: Use a custom LLM base URL
     # LLM_BASE_URL: 'https://custom-api.example.com'
     # Optional: Choose review style ('standard' or 'roasted')
     # - 'standard': Pragmatic, constructive feedback (default)
     # - 'roasted': Linus Torvalds style brutally honest review
     REVIEW_STYLE: standard
+    # Optional: Choose review mode ('sdk' or 'cloud')
+    # - 'sdk': Run locally in GitHub Actions (default)
+    # - 'cloud': Launch in OpenHands Cloud (requires OPENHANDS_CLOUD_API_KEY)
+    REVIEW_MODE: sdk
 ```
 
 ### 4. Create the review label
@@ -101,3 +110,28 @@ There are two ways to trigger an automated review of a pull request:
 5. Review comments will be posted to the PR when complete
 
 **Note**: Both methods require write access to the repository, ensuring only authorized users can trigger the AI review.
+
+### Review Modes
+
+#### SDK Mode (Default)
+
+In SDK mode (`REVIEW_MODE=sdk`), the review runs entirely within the GitHub Actions runner:
+
+- The agent analyzes the PR diff and posts inline comments
+- The CI job waits for the review to complete
+- Cost and token usage are logged in the CI output
+
+#### Cloud Mode
+
+In Cloud mode (`REVIEW_MODE=cloud`), the review is launched in OpenHands Cloud:
+
+- A new conversation is created in OpenHands Cloud
+- The CI job posts a comment with a link to track progress
+- The CI job exits immediately (fast CI completion)
+- The review continues asynchronously in the cloud
+- When complete, the agent posts inline comments to the PR
+
+Cloud mode is useful when:
+- You want faster CI completion times
+- You want to track review progress in the OpenHands Cloud UI
+- You want to interact with the review conversation