Skip to main content
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.

​
Quick Start

# 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

​
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

​
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 skill file to your repository. This is the recommended approach for customization.

​
How It Works

The PR review agent uses skills from the OpenHands/extensions repository by default. You can add your project-specific guidelines alongside the default skill by creating a custom skill file.
Skill paths: Place skills in .agents/skills/ (recommended). The legacy path .openhands/skills/ is also supported. See Skill Loading Precedence for details.

​
Example: Custom Code Review Skill

Create .agents/skills/custom-codereview-guide.md in your repository: 
---
name: custom-codereview-guide
description: Project-specific review guidelines for MyProject
triggers:
- /codereview
---

# MyProject-Specific Review Guidelines

In addition to general code review practices, check for:

## Project Conventions

- All API endpoints must have OpenAPI documentation
- Database migrations must be reversible
- Feature flags required for new features

## Architecture Rules

- No direct database access from controllers
- All external API calls must go through the gateway service

## Communication Style

- Be direct and constructive
- Use GitHub suggestion syntax for code fixes
Note: These rules supplement the default code-review skill, not replace it.
How skill merging works: Using a unique name like custom-codereview-guide allows BOTH your custom skill AND the default code-review skill to be triggered by /codereview. When triggered, skill content is concatenated into the agent’s context (public skills first, then your custom skills). There is no smart merging—if guidelines conflict, the agent sees both and must reconcile them.If your skill has name: code-review (matching the public skill’s name), it will completely override the default public skill instead of supplementing it.
Migrating from override to supplement: If you previously created a skill with name: code-review to override the default, rename it (e.g., to my-project-review) to receive guidelines from both skills instead.

​
Benefits of Custom Skills

  1. No forking required: Keep using the official SDK while customizing behavior
  2. Version controlled: Your review guidelines live in your repository
  3. Easy updates: SDK updates don’t overwrite your customizations
  4. Team alignment: Everyone uses the same review standards
  5. Composable: Add project-specific rules alongside default guidelines
See the software-agent-sdk’s own custom-codereview-guide skill for a complete example.

​
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

InputDescriptionRequiredDefault
llm-modelLLM model to useYes-
llm-base-urlLLM base URL (optional)No''
review-styleReview style: ‘standard’ or ‘roasted’Noroasted
sdk-versionGit ref for SDK (tag, branch, or commit SHA)Nomain
sdk-repoSDK repository (owner/repo)NoOpenHands/software-agent-sdk
llm-api-keyLLM API keyYes-
github-tokenGitHub token for API accessYes-