Automated Code Review

Set up automated PR reviews using OpenHands and the Software Agent SDK

View Example Plugin

Check out the complete PR review plugin with ready-to-use code and configuration.

Automated code review helps maintain code quality, catch bugs early, and enforce coding standards consistently across your team. OpenHands provides a GitHub Actions workflow powered by the Software Agent SDK that automatically reviews pull requests and posts inline comments directly on your PRs.

Overview

The OpenHands PR Review workflow is a GitHub Actions workflow that:

• Triggers automatically when PRs are opened or when you request a review
• Analyzes code changes in the context of your entire repository
• Posts inline comments directly on specific lines of code in the PR
• Provides fast feedback - typically within 2-3 minutes

How It Works

The PR review workflow uses the OpenHands Software Agent SDK to analyze your code changes:

1. Trigger: The workflow runs when:

   • A new non-draft PR is opened
   • A draft PR is marked as ready for review
   • The review-this label is added to a PR
   • openhands-agent is requested as a reviewer

2. Analysis: The agent receives the complete PR diff and uses two skills:

   • /codereview: Analyzes code for quality, security, data structures, and best practices with a focus on simplicity and pragmatism
   • /github-pr-review: Posts structured inline comments via the GitHub API

3. Output: Review comments are posted directly on the PR with:

   • Priority labels (🔴 Critical, 🟠 Important, 🟡 Suggestion, 🟢 Nit)
   • Specific line references
   • Actionable suggestions with code examples

Quick Start

1. Copy the workflow file

   Create .github/workflows/pr-review-by-openhands.yml in your repository:

   name: PR Review by OpenHands
   
   on:
     pull_request_target:
       types: [opened, ready_for_review, labeled, review_requested]
   
   permissions:
     contents: read
     pull-requests: write
     issues: write
   
   jobs:
     pr-review:
       if: |
         (github.event.action == 'opened' && github.event.pull_request.draft == false) ||
         github.event.action == 'ready_for_review' ||
         github.event.label.name == 'review-this' ||
         github.event.requested_reviewer.login == 'openhands-agent'
       runs-on: ubuntu-latest
       steps:
         - name: Run PR Review
           uses: OpenHands/extensions/plugins/pr-review@main
           with:
             llm-model: anthropic/claude-sonnet-4-5-20250929
             llm-api-key: ${{ secrets.LLM_API_KEY }}
             github-token: ${{ secrets.GITHUB_TOKEN }}
   
2. Add your LLM API key

   Go to your repository’s Settings → Secrets and variables → Actions and add:

   • LLM_API_KEY: Your LLM API key (get one from OpenHands LLM Provider)
3. Create the review label

   Create a review-this label in your repository:

   1. Go to Issues → Labels
   2. Click New label
   3. Name: review-this
   4. Description: Trigger OpenHands PR review
4. Trigger a review

   Open a PR and either:

   • Add the review-this label, OR
   • Request openhands-agent as a reviewer

Composite Action

Action Path Updated: The PR review action has moved to the extensions repository. If your workflow still references the old path, update it:

• Old: OpenHands/software-agent-sdk/.github/actions/pr-review@main
• New: OpenHands/extensions/plugins/pr-review@main

The workflow uses a reusable composite action that handles all the setup automatically:

• Checking out the extensions repository at the specified version
• Setting up Python and dependencies
• Running the PR review agent (from extensions repo)
• Uploading logs as artifacts

Action Inputs

Input	Description	Required	Default
agent-kind	Review backend: openhands for the standard SDK agent or acp for an ACP-compatible agent server	No	openhands
llm-model	LLM model(s). Comma-separated to run multiple reviews and compare results (A/B testing). In ACP mode this is passed to the ACP server when supported.	No	anthropic/claude-sonnet-4-5-20250929
acp-command	Command used to start the ACP server. Required when agent-kind is acp. Examples: npx -y @zed-industries/codex-acp@0.12.0, codex-acp, claude-agent-acp, npx -y @agentclientprotocol/claude-agent-acp	Yes for ACP mode	''
acp-prompt-timeout	Timeout in seconds for one ACP prompt turn	No	1800
llm-base-url	LLM base URL (for custom endpoints)	No	''
review-style	[DEPRECATED] Previously chose between standard and roasted. Now ignored — the styles have been merged.	No	roasted
require-evidence	Require the reviewer to enforce an Evidence section in the PR description with end-to-end proof	No	'false'
use-sub-agents	Enable sub-agent delegation for file-level reviews in openhands mode. Ignored in ACP mode.	No	'false'
extensions-repo	Extensions repository (owner/repo)	No	OpenHands/extensions
extensions-version	Git ref for extensions (tag, branch, or commit SHA)	No	main
openhands-sdk-package	Package spec passed to uv --with; override only when pinning a specific SDK build for testing or rollout control	No	openhands-sdk
llm-api-key	LLM API key. Required when agent-kind is openhands; ignored in ACP mode.	Yes for OpenHands mode	-
github-token	GitHub token for API access	Yes	-
lmnr-api-key	Laminar API key for observability	No	''
enable-uv-cache	Enable setup-uv’s GitHub Actions cache for Python deps. Default false for security.	No	'false'

Use extensions-version to pin to a specific version tag (e.g., v1.0.0) for production stability, or use main to always get the latest features. The extensions repository contains the PR review plugin scripts.

Experimental: ACP Review Backend

The PR review action can run through an ACP-compatible agent server by setting agent-kind: acp. In this mode, OpenHands still loads the review skills and plugin prompt context, but the ACP server owns model access, authentication, and tool execution.

Use ACP mode when your runner already has an authenticated ACP CLI available. The action does not install ACP CLIs for you; install and authenticate the ACP server in workflow steps before invoking the PR review action.

ACP mode is experimental. Use it on trusted self-hosted runners where you control the installed ACP command and the authentication material. Do not expose subscription credentials to workflows that run untrusted pull request code.

Codex ACP Example

To use Codex ACP, first install the Codex CLI and complete device-code login on a trusted machine:

codex login --device-auth
codex login status

Then create a base64-encoded secret from the generated auth file:

# Linux
base64 -w 0 "$HOME/.codex/auth.json"

# macOS
base64 < "$HOME/.codex/auth.json" | tr -d '\n'

Store the printed value as a repository or organization secret named CODEX_AUTH_JSON_B64. The workflow can then restore that file on a self-hosted runner, start Codex ACP with npx, and run the review:

name: PR Review by OpenHands

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: [self-hosted]
    timeout-minutes: 30
    steps:
      - name: Restore Codex auth
        env:
          CODEX_AUTH_JSON_B64: ${{ secrets.CODEX_AUTH_JSON_B64 }}
        run: |
          if [ -z "$CODEX_AUTH_JSON_B64" ]; then
            echo "Error: CODEX_AUTH_JSON_B64 is required for Codex ACP review."
            exit 1
          fi
          mkdir -p "$HOME/.codex"
          if ! printf '%s' "$CODEX_AUTH_JSON_B64" | base64 -d > "$HOME/.codex/auth.json"; then
            echo "Error: Failed to decode CODEX_AUTH_JSON_B64 — check the base64 value."
            exit 1
          fi
          chmod 600 "$HOME/.codex/auth.json"

      - name: Run PR Review
        uses: OpenHands/extensions/plugins/pr-review@main
        with:
          agent-kind: acp
          acp-command: npx -y @zed-industries/codex-acp@0.12.0
          llm-model: o3
          github-token: ${{ secrets.GITHUB_TOKEN }}

      - name: Cleanup Codex auth
        if: always()
        run: rm -f "$HOME/.codex/auth.json"

Customization

Repository-Specific Review Guidelines

Add repo-specific review rules by creating a skill file at .agents/skills/custom-codereview-guide.md:

---
name: custom-codereview-guide
description: Custom code review guidelines for this repository
triggers:
- /codereview
---

# Repository Code Review Guidelines

You are reviewing code for [Your Project Name]. Follow these guidelines:

## Review Decisions

### When to APPROVE
- Configuration changes following existing patterns
- Documentation-only changes
- Test-only changes without production code changes
- Simple additions following established conventions

### When to COMMENT
- Issues that need attention (bugs, security concerns)
- Suggestions for improvement
- Questions about design decisions

## Core Principles

1. **[Your Principle 1]**: Description
2. **[Your Principle 2]**: Description

## What to Check

- **[Category 1]**: What to look for
- **[Category 2]**: What to look for

## Repository Conventions

- Use [your linter] for style checking
- Follow [your style guide]
- Tests should be in [your test directory]

Do not name your skill code-review. The pr-review plugin ships its own code-review skill, and plugin skills override project skills with the same name. Use a different name (e.g. custom-codereview-guide) with the /codereview trigger so both skills are active — the plugin provides the review framework while your skill adds repo-specific rules.

The skill file must use /codereview as the trigger so it activates alongside the default review behavior. See the software-agent-sdk’s own custom-codereview-guide for a complete example.

Workflow Configuration

Customize the workflow by modifying the action inputs:

- name: Run PR Review
  uses: OpenHands/extensions/plugins/pr-review@main
  with:
    # Change the LLM model
    llm-model: anthropic/claude-sonnet-4-5-20250929
    # Use a custom LLM endpoint
    llm-base-url: https://your-llm-proxy.example.com
    # Pin to a specific extensions version for stability
    extensions-version: main
    # Secrets
    llm-api-key: ${{ secrets.LLM_API_KEY }}
    github-token: ${{ secrets.GITHUB_TOKEN }}

Trigger Customization

Modify when reviews are triggered by editing the workflow conditions:

# Only trigger on label (disable auto-review on PR open)
if: github.event.label.name == 'review-this'

# Only trigger when specific reviewer is requested
if: github.event.requested_reviewer.login == 'openhands-agent'

# Trigger on all PRs (including drafts)
if: |
  github.event.action == 'opened' ||
  github.event.action == 'synchronize'

Security Considerations

The workflow uses pull_request_target so the code review agent can work properly for PRs from forks. Only users with write access can trigger reviews via labels or reviewer requests.

Potential Risk: A malicious contributor could submit a PR from a fork containing code designed to exfiltrate your LLM_API_KEY when the review agent analyzes their code.

To mitigate this, the PR review workflow passes API keys as SDK secrets rather than environment variables, which prevents the agent from directly accessing these credentials during code execution.

Example Reviews

See real automated reviews in action on the OpenHands Software Agent SDK repository:

PR	Description	Review Highlights
#1927	Composite GitHub Action refactor	Comprehensive review with 🔴 Critical, 🟠 Important, and 🟡 Suggestion labels
#1916	Add example for reconstructing messages	Critical issues flagged with clear explanations
#1904	Update code-review skill guidelines	APPROVED review highlighting key strengths
#1889	Fix tmux race condition	Technical review of concurrency fix with dual-lock strategy analysis

Troubleshooting

Review not triggering

• Ensure the LLM_API_KEY secret is set correctly
• Check that the label name matches exactly (review-this)
• Verify the workflow file is in .github/workflows/
• Check the Actions tab for workflow run errors

Review comments not appearing

• Ensure GITHUB_TOKEN has pull-requests: write permission
• Check the workflow logs for API errors
• Verify the PR is not from a fork with restricted permissions

Review taking too long

• Large PRs may take longer to analyze
• Consider splitting large PRs into smaller ones
• Check if the LLM API is experiencing delays

Automate This

You can schedule daily code reviews using OpenHands Automations. Copy this prompt into a new conversation to set one up:

Create an automation called "Daily Code Review" that runs every weekday at 9 AM.

It should:
1. Find all open PRs that have no reviews yet
2. For each PR, review the diff for bugs, style issues, and security concerns
3. Post a summary of findings as a comment on each PR

Learn more at https://docs.openhands.dev/openhands/usage/use-cases/code-review

For inline review comments on every push, use the pr-review plugin as a GitHub Action instead.

Related Resources

• PR Review Plugin - Full workflow example and agent script
• Composite Action - Reusable GitHub Action for PR reviews
• Software Agent SDK - Build your own AI-powered workflows
• GitHub Integration - Set up GitHub integration for OpenHands Cloud
• Skills Documentation - Learn more about OpenHands skills