PR Review

The reference workflow is available here!

Automatically review pull requests, providing feedback on code quality, security, and best practices. Reviews can be triggered in two ways:

Requesting openhands-agent as a reviewer
Adding the review-this label to the PR

The reference workflow triggers on either the “review-this” label or when the openhands-agent account is requested as a reviewer. In OpenHands organization repositories, openhands-agent has access, so this works as-is. In your own repositories, requesting openhands-agent will only work if that account is added as a collaborator or is part of a team with access. If you don’t plan to grant access, use the label trigger instead, or change the condition to a reviewer handle that exists in your repo.

Review Modes

The PR review workflow supports two modes:

Mode	Description	Required Secrets
SDK Mode (default)	Runs the agent locally in GitHub Actions	`LLM_API_KEY`, `GITHUB_TOKEN`
Cloud Mode	Runs asynchronously in OpenHands Cloud	`OPENHANDS_CLOUD_API_KEY`, `GITHUB_TOKEN`

Cloud Mode Benefits

No LLM setup - Uses your OpenHands Cloud account’s configured LLM
Faster CI completion - Workflow exits immediately; review runs in background
Track progress - Posts a comment on the PR with a link to the conversation URL

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 to connect your GitHub account to OpenHands Cloud.

Quick Start

SDK Mode (Default)
Cloud Mode

# 1. Copy workflow to your repository
cp examples/03_github_workflows/02_pr_review/workflow.yml .github/workflows/pr-review.yml

# 2. Configure secrets in GitHub Settings → Secrets
# Add: LLM_API_KEY

# 3. (Optional) Create a "review-this" label in your repository
# Go to Issues → Labels → New label
# You can also trigger reviews by requesting "openhands-agent" as a reviewer

# 1. Copy workflow to your repository
cp examples/03_github_workflows/02_pr_review/workflow.yml .github/workflows/pr-review.yml

# 2. Configure secrets in GitHub Settings → Secrets
# Add: OPENHANDS_CLOUD_API_KEY (see https://docs.openhands.dev/openhands/usage/cloud/cloud-api#obtaining-an-api-key)
# GITHUB_TOKEN is auto-available in GitHub Actions

# 3. Update the workflow to use cloud mode:
# Set mode: cloud and remove llm-api-key

# 4. (Optional) Create a "review-this" label in your repository

Features

Fast Reviews - Results posted on the PR in only 2 or 3 minutes
Comprehensive Analysis - Analyzes the changes given the repository context. Covers code quality, security, best practices
GitHub Integration - Posts comments directly to the PR
Customizable - Add your own code review guidelines without forking
Two Modes - Run locally (SDK) or in the cloud (asynchronous)

Security

Users with write access (maintainers) can trigger reviews by requesting openhands-agent as a reviewer or adding the review-this label.
Maintainers need to read the PR to make sure it’s safe to run.

Customizing the Code Review

Instead of forking the agent_script.py, you can customize the code review behavior by adding a .agents/skills/code-review.md file to your repository. This is the recommended approach for customization.

How It Works

The PR review agent uses skills from the OpenHands/skills repository by default. When you add a .openhands/skills/code-review.md file to your repository, it overrides the default skill with your custom guidelines.

Example: Custom Code Review Skill

Create .openhands/skills/code-review.md in your repository:

---
name: code-review
description: Custom code review guidelines for my project
triggers:
- /codereview
---

# My Project Code Review Guidelines

You are a code reviewer for this project. Follow these guidelines:

## Review Decisions

- **APPROVE** straightforward changes (config updates, typo fixes, documentation)
- **COMMENT** when you have feedback or concerns

## What to Check

- Code follows our project conventions
- Tests are included for new functionality
- No security vulnerabilities introduced
- Documentation is updated if needed

## Communication Style

- Be direct and constructive
- Use GitHub suggestion syntax for code fixes
- Approve quickly when code is good

Benefits of Custom Skills

No forking required: Keep using the official SDK while customizing behavior
Version controlled: Your review guidelines live in your repository
Easy updates: SDK updates don’t overwrite your customizations
Team alignment: Everyone uses the same review standards

See the software-agent-sdk’s own code-review skill for a complete example of a custom code review skill.

Reference Workflow

This example is available on GitHub: examples/03_github_workflows/02_pr_review/

examples/03_github_workflows/02_pr_review/workflow.yml

---
# OpenHands PR Review Workflow
#
# To set this up:
#  1. Copy this file to .github/workflows/pr-review.yml in your repository
#  2. Add LLM_API_KEY to repository secrets
#  3. Customize the inputs below as needed
#  4. Commit this file to your repository
#  5. Trigger the review by either:
#     - Adding the "review-this" label to any PR, OR
#     - Requesting openhands-agent as a reviewer
#
# For more information, see:
# https://github.com/OpenHands/software-agent-sdk/tree/main/examples/03_github_workflows/02_pr_review
name: PR Review by OpenHands

on:
    # Trigger when a label is added or a reviewer is requested
    pull_request:
        types: [labeled, review_requested]

permissions:
    contents: read
    pull-requests: write
    issues: write

jobs:
    pr-review:
        # Run when review-this label is added OR openhands-agent is requested as reviewer
        if: |
            github.event.label.name == 'review-this' ||
            github.event.requested_reviewer.login == 'openhands-agent'
        runs-on: ubuntu-latest
        steps:
            - name: Checkout for composite action
              uses: actions/checkout@v4
              with:
                  repository: OpenHands/software-agent-sdk
                  # Use a specific version tag or branch (e.g., 'v1.0.0' or 'main')
                  ref: main
                  sparse-checkout: .github/actions/pr-review

            - name: Run PR Review
              uses: ./.github/actions/pr-review
              with:
                  # LLM configuration
                  llm-model: anthropic/claude-sonnet-4-5-20250929
                  llm-base-url: ''
                  # Review style: roasted (other option: standard)
                  review-style: roasted
                  # SDK version to use (version tag or branch name)
                  sdk-version: main
                  # Secrets
                  llm-api-key: ${{ secrets.LLM_API_KEY }}
                  github-token: ${{ secrets.GITHUB_TOKEN }}

Action Inputs

Input	Description	Required	Default
`mode`	Review mode: `sdk` or `cloud`	No	`sdk`
`llm-model`	LLM model (SDK mode only)	SDK mode	`anthropic/claude-sonnet-4-5-20250929`
`llm-base-url`	LLM base URL (SDK mode only)	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 (SDK mode only)	SDK mode	-
`github-token`	GitHub token for API access	Yes	-
`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`

Cloud Mode Workflow Example

For cloud mode, you don’t need an LLM API key - just the cloud API key:

name: PR Review by OpenHands (Cloud Mode)

on:
    pull_request:
        types: [labeled, review_requested]

permissions:
    contents: read
    pull-requests: write
    issues: write

jobs:
    pr-review:
        if: |
            github.event.label.name == 'review-this' ||
            github.event.requested_reviewer.login == 'openhands-agent'
        runs-on: ubuntu-latest
        steps:
            - name: Checkout for composite action
              uses: actions/checkout@v4
              with:
                  repository: OpenHands/software-agent-sdk
                  ref: main
                  sparse-checkout: .github/actions/pr-review

            - name: Run PR Review
              uses: ./.github/actions/pr-review
              with:
                  mode: cloud
                  review-style: roasted
                  openhands-cloud-api-key: ${{ secrets.OPENHANDS_CLOUD_API_KEY }}
                  github-token: ${{ secrets.GITHUB_TOKEN }}

In cloud mode, the workflow posts a comment on the PR with a link to the conversation URL, then exits immediately. The agent runs asynchronously in OpenHands Cloud and posts review comments when done.

Guides

Architecture

API Reference

Review Modes

Cloud Mode Benefits

Cloud Mode Prerequisites

Quick Start

Features

Security

Customizing the Code Review

How It Works

Example: Custom Code Review Skill

Benefits of Custom Skills

Reference Workflow

Action Inputs

Cloud Mode Workflow Example

Guides

Architecture

API Reference

​Review Modes

​Cloud Mode Benefits

​Cloud Mode Prerequisites

​Quick Start

​Features

​Security

​Customizing the Code Review

​How It Works

​Example: Custom Code Review Skill

​Benefits of Custom Skills

​Reference Workflow

​Action Inputs

​Cloud Mode Workflow Example

​Related Files

Review Modes

Cloud Mode Benefits

Cloud Mode Prerequisites

Quick Start

Features

Security

Customizing the Code Review

How It Works

Example: Custom Code Review Skill

Benefits of Custom Skills

Reference Workflow

Action Inputs

Cloud Mode Workflow Example

Related Files