feat: Add cloud mode for PR review workflow

.github/actions/pr-review/action.yml

@@ -8,35 +8,47 @@ branding:
     color: blue
 
 inputs:
+    mode:
+        description: "Review mode: 'sdk' (run locally) or 'cloud' (run in OpenHands Cloud)"
+        required: false
+        default: sdk
     llm-model:
-        description: LLM model to use for the review
+        description: LLM model to use for the review (sdk mode only, cloud uses user's configured LLM)
         required: false
         default: anthropic/claude-sonnet-4-5-20250929
     llm-base-url:
-        description: LLM base URL (optional, for custom LLM endpoints)
+        description: LLM base URL (sdk mode only, optional for custom LLM endpoints)
         required: false
         default: ''
     review-style:
-        description: "Review style: 'standard' (balanced review covering style, readability, and security) or 'roasted' (Linus Torvalds-style brutally honest
-            feedback focusing on data structures, simplicity, and pragmatism)"
+        description: "Review style: 'standard' (balanced review) or 'roasted' (Linus Torvalds-style)"
         required: false
         default: roasted
     sdk-repo:
         description: GitHub repository for the SDK (owner/repo)
         required: false
         default: OpenHands/software-agent-sdk
     sdk-version:
-        description: Git ref to use for the SDK (tag, branch, or commit SHA, e.g., v1.0.0, main, or abc1234)
+        description: Git ref to use for the SDK (tag, branch, or commit SHA)
         required: false
         default: main
     llm-api-key:
-        description: LLM API key (required)
-        required: true
+        description: LLM API key (required for 'sdk' mode only - cloud mode uses your OpenHands Cloud LLM settings)
+        required: false
+        default: ''
     github-token:
-        description: GitHub token for API access (required)
+        description: GitHub token for API access (required for both modes - used to post initial comment in cloud mode)
         required: true
+    openhands-cloud-api-key:
+        description: OpenHands Cloud API key (required for 'cloud' mode), get it from https://app.all-hands.dev/settings/api-keys
+        required: false
+        default: ''
+    openhands-cloud-api-url:
+        description: OpenHands Cloud API URL
+        required: false
+        default: https://app.all-hands.dev
     lmnr-api-key:
-        description: Laminar API key for observability (optional)
+        description: Laminar API key for observability (optional, sdk mode only)
         required: false
         default: ''
 
@@ -78,40 +90,68 @@ runs:
         - name: Install OpenHands dependencies
           shell: bash
           run: |
-              uv pip install --system ./software-agent-sdk/openhands-sdk ./software-agent-sdk/openhands-tools lmnr
+              uv pip install --system ./software-agent-sdk/openhands-sdk ./software-agent-sdk/openhands-tools ./software-agent-sdk/openhands-workspace lmnr requests
 
         - name: Check required configuration
           shell: bash
           env:
+              MODE: ${{ inputs.mode }}
               LLM_API_KEY: ${{ inputs.llm-api-key }}
               GITHUB_TOKEN: ${{ inputs.github-token }}
+              OPENHANDS_CLOUD_API_KEY: ${{ inputs.openhands-cloud-api-key }}
           run: |
-              if [ -z "$LLM_API_KEY" ]; then
-                echo "Error: llm-api-key is required."
+              echo "Mode: $MODE"
+
+              # GITHUB_TOKEN is required for both modes
+              if [ -z "$GITHUB_TOKEN" ]; then
+                echo "Error: github-token is required for both modes."
                 exit 1
               fi
-              if [ -z "$GITHUB_TOKEN" ]; then
-                echo "Error: github-token is required."
+
+              if [ "$MODE" = "sdk" ]; then
+                # SDK mode requires LLM_API_KEY for local execution
+                if [ -z "$LLM_API_KEY" ]; then
+                  echo "Error: llm-api-key is required for 'sdk' mode."
+                  exit 1
+                fi
+                echo "SDK mode: LLM runs locally in GitHub Actions"
+              elif [ "$MODE" = "cloud" ]; then
+                # Cloud mode requires OPENHANDS_CLOUD_API_KEY (no LLM_API_KEY needed)
+                if [ -z "$OPENHANDS_CLOUD_API_KEY" ]; then
+                  echo "Error: openhands-cloud-api-key is required for 'cloud' mode."
+                  exit 1
+                fi
+                echo "Cloud mode: Review runs in OpenHands Cloud using your configured LLM"
+              else
+                echo "Error: mode must be 'sdk' or 'cloud', got '$MODE'."
                 exit 1
               fi
 
               echo "PR Number: ${{ github.event.pull_request.number }}"
               echo "PR Title: ${{ github.event.pull_request.title }}"
               echo "Repository: ${{ github.repository }}"
               echo "SDK Version: ${{ inputs.sdk-version }}"
-              echo "LLM model: ${{ inputs.llm-model }}"
-              if [ -n "${{ inputs.llm-base-url }}" ]; then
-                echo "LLM base URL: ${{ inputs.llm-base-url }}"
+              if [ "$MODE" = "sdk" ]; then
+                echo "LLM model: ${{ inputs.llm-model }}"
+                if [ -n "${{ inputs.llm-base-url }}" ]; then
+                  echo "LLM base URL: ${{ inputs.llm-base-url }}"
+                fi
+              else
+                echo "OpenHands Cloud API URL: ${{ inputs.openhands-cloud-api-url }}"
+                echo "Note: LLM is configured in your OpenHands Cloud account"
               fi
 
         - name: Run PR review
           shell: bash
           env:
+              MODE: ${{ inputs.mode }}
               LLM_MODEL: ${{ inputs.llm-model }}
               LLM_BASE_URL: ${{ inputs.llm-base-url }}
               REVIEW_STYLE: ${{ inputs.review-style }}
               LLM_API_KEY: ${{ inputs.llm-api-key }}
               GITHUB_TOKEN: ${{ inputs.github-token }}
+              OPENHANDS_CLOUD_API_KEY: ${{ inputs.openhands-cloud-api-key }}
+              OPENHANDS_CLOUD_API_URL: ${{ inputs.openhands-cloud-api-url }}
               LMNR_PROJECT_API_KEY: ${{ inputs.lmnr-api-key }}
               PR_NUMBER: ${{ github.event.pull_request.number }}
               PR_TITLE: ${{ github.event.pull_request.title }}

examples/03_github_workflows/02_pr_review/README.md

@@ -13,6 +13,9 @@ This example demonstrates how to set up a GitHub Actions workflow for automated
 
 ## Features
 
+- **Two Review Modes**:
+  - **SDK Mode** (default): Runs the agent locally in GitHub Actions
+  - **Cloud Mode**: Launches the review in OpenHands Cloud for faster CI completion
 - **Automatic Trigger**: Reviews are triggered when:
   - The `review-this` label is added to a PR, OR
   - openhands-agent is requested as a reviewer
@@ -54,21 +57,33 @@ cp examples/03_github_workflows/02_pr_review/workflow.yml .github/workflows/pr-r
 
 ### 2. Configure secrets
 
-Set the following secrets in your GitHub repository settings:
+Set the following secrets in your GitHub repository settings based on your chosen mode:
 
+**For SDK Mode (default):**
 - **`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)
+- **`GITHUB_TOKEN`** (auto-available): Used for PR diff and posting comments
 
-**Note**: The workflow automatically uses the `GITHUB_TOKEN` secret that's available in all GitHub Actions workflows.
+**For Cloud Mode:**
+- **`OPENHANDS_CLOUD_API_KEY`** (required): Your OpenHands Cloud API key
+  - Get one from your [OpenHands Cloud account settings](https://app.all-hands.dev/settings/api-keys)
+- **`GITHUB_TOKEN`** (auto-available): Used to post initial comment with conversation URL
+- **`LLM_API_KEY`** (optional): Your LLM API key. If not provided, uses the LLM configured in your OpenHands Cloud account.
+
+**Note**: Cloud mode uses the LLM settings configured in your OpenHands Cloud account by default. You can optionally override this by providing `LLM_API_KEY`. The workflow uses `GITHUB_TOKEN` to post a comment linking to the conversation URL. The agent running in cloud uses your account's GitHub access for the actual review.
 
 ### 3. Customize the workflow (optional)
 
-Edit `.github/workflows/pr-review-by-openhands.yml` to customize the inputs:
+Edit `.github/workflows/pr-review-by-openhands.yml` to customize the inputs.
+
+**SDK Mode Configuration (default):**
 
 ```yaml
 - name: Run PR Review
   uses: ./.github/actions/pr-review
   with:
+      # Review mode: 'sdk' runs the agent locally in GitHub Actions
+      mode: sdk
       # LLM configuration
       llm-model: anthropic/claude-sonnet-4-5-20250929
       llm-base-url: ''
@@ -83,6 +98,38 @@ Edit `.github/workflows/pr-review-by-openhands.yml` to customize the inputs:
       github-token: ${{ secrets.GITHUB_TOKEN }}
 ```
 
+**Cloud Mode Configuration:**
+
+```yaml
+- name: Run PR Review
+  uses: ./.github/actions/pr-review
+  with:
+      # Review mode: 'cloud' runs in OpenHands Cloud
+      mode: cloud
+      # Review style: roasted (other option: standard)
+      review-style: roasted
+      # SDK git ref to use
+      sdk-version: main
+      # Cloud mode secrets
+      openhands-cloud-api-key: ${{ secrets.OPENHANDS_CLOUD_API_KEY }}
+      github-token: ${{ secrets.GITHUB_TOKEN }}
+      # Optional: Override the cloud's default LLM with your own
+      # llm-api-key: ${{ secrets.LLM_API_KEY }}
+      # llm-model: anthropic/claude-sonnet-4-5-20250929
+      # Optional: custom cloud API URL
+      # openhands-cloud-api-url: https://app.all-hands.dev
+```
+
+**Cloud Mode Benefits:**
+- **Faster CI completion**: Starts the review and exits immediately
+- **Track progress in UI**: Posts a comment with a link to the conversation URL
+- **Interactive**: Users can interact with the review conversation in the cloud UI
+
+**Cloud Mode Prerequisites:**
+> ⚠️ The OpenHands Cloud account that owns the `OPENHANDS_CLOUD_API_KEY` must have GitHub access to the repository you want to review. The agent running in cloud uses your account's GitHub credentials to fetch the PR diff and post review comments.
+>
+> Follow the [GitHub Installation Guide](https://docs.openhands.dev/openhands/usage/cloud/github-installation) to connect your GitHub account to OpenHands Cloud.
+
 ### 4. Create the review label
 
 Create a `review-this` label in your repository:
@@ -184,14 +231,17 @@ This workflow uses a reusable composite action located at `.github/actions/pr-re
 
 | Input | Description | Required | Default |
 |-------|-------------|----------|---------|
+| `mode` | Review mode: 'sdk' or 'cloud' | No | `sdk` |
 | `llm-model` | LLM model to use | No | `anthropic/claude-sonnet-4-5-20250929` |
-| `llm-base-url` | LLM base URL (optional) | No | `''` |
+| `llm-base-url` | LLM base URL (optional for custom endpoints) | No | `''` |
 | `review-style` | Review style: 'standard' or 'roasted' | No | `roasted` |
 | `sdk-version` | Git ref for SDK (tag, branch, or commit SHA) | No | `main` |
 | `sdk-repo` | SDK repository (owner/repo) | No | `OpenHands/software-agent-sdk` |
-| `llm-api-key` | LLM API key | Yes | - |
+| `llm-api-key` | LLM API key (required for SDK mode, optional for cloud mode) | SDK mode | - |
 | `github-token` | GitHub token for API access | Yes | - |
-| `lmnr-api-key` | Laminar API key for observability (optional) | No | - |
+| `openhands-cloud-api-key` | OpenHands Cloud API key (cloud mode only) | cloud mode | - |
+| `openhands-cloud-api-url` | OpenHands Cloud API URL | No | `https://app.all-hands.dev` |
+| `lmnr-api-key` | Laminar API key for observability (sdk mode only) | No | - |
 
 ## Review Evaluation (Observability)