> ## Documentation Index
> Fetch the complete documentation index at: https://docs.openhands.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# PR Review

> Use OpenHands Agent to generate meaningful pull request review

> The reference workflow is available [here](#reference-workflow)!

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

<Note>
  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.
</Note>

## Quick Start

```bash theme={null}
# 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](https://github.com/OpenHands/extensions) repository by default. You can add your project-specific guidelines alongside the default skill by creating a custom skill file.

<Note>
  **Skill paths**: Place skills in `.agents/skills/` (recommended). The legacy path `.openhands/skills/` is also supported. See [Skill Loading Precedence](/overview/skills#skill-loading-precedence) for details.
</Note>

### Example: Custom Code Review Skill

Create `.agents/skills/custom-codereview-guide.md` in your repository:

```markdown theme={null}
---
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>
  **Note**: These rules supplement the default `code-review` skill, not replace it.
</Note>

<Tip>
  **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.
</Tip>

<Note>
  **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.
</Note>

### 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

<Note>
  See the [software-agent-sdk's own custom-codereview-guide skill](https://github.com/OpenHands/software-agent-sdk/blob/main/.agents/skills/custom-codereview-guide.md) for a complete example.
</Note>

## Reference Workflow

<Note>
  This example is available on GitHub: [examples/03\_github\_workflows/02\_pr\_review/](https://github.com/OpenHands/software-agent-sdk/tree/main/examples/03_github_workflows/02_pr_review)
</Note>

```yaml icon="yaml" expandable examples/03_github_workflows/02_pr_review/workflow.yml theme={null}
---
# 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 model(s) to use. Can be comma-separated for A/B testing
                  # - one model will be randomly selected per review
                  llm-model: anthropic/claude-sonnet-4-5-20250929
                  llm-base-url: ''
                  # [DEPRECATED] review-style is no longer used; standard and roasted are merged
                  # review-style: roasted
                  # Extensions version to use (version tag or branch name)
                  extensions-version: main
                  # Secrets
                  llm-api-key: ${{ secrets.LLM_API_KEY }}
                  github-token: ${{ secrets.GITHUB_TOKEN }}
```

### Action Inputs

| Input                | Description                                                                                                     | Required | Default                |
| -------------------- | --------------------------------------------------------------------------------------------------------------- | -------- | ---------------------- |
| `llm-model`          | LLM model to use                                                                                                | Yes      | -                      |
| `llm-base-url`       | LLM base URL (optional)                                                                                         | No       | `''`                   |
| `review-style`       | **\[DEPRECATED]** Previously chose between `standard` and `roasted`. Now ignored — the styles have been merged. | No       | `roasted`              |
| `extensions-version` | Git ref for extensions (tag, branch, or commit SHA)                                                             | No       | `main`                 |
| `extensions-repo`    | Extensions repository (owner/repo)                                                                              | No       | `OpenHands/extensions` |
| `llm-api-key`        | LLM API key                                                                                                     | Yes      | -                      |
| `github-token`       | GitHub token for API access                                                                                     | Yes      | -                      |

## Related Files

* [PR Review Plugin](https://github.com/OpenHands/extensions/tree/main/plugins/pr-review) - Complete plugin with scripts and skills (in extensions repo)
* [Agent Script](https://github.com/OpenHands/extensions/blob/main/plugins/pr-review/scripts/agent_script.py) - Main review agent script
* [Prompt Template](https://github.com/OpenHands/extensions/blob/main/plugins/pr-review/scripts/prompt.py) - Review prompt template
* [Example Workflow](https://github.com/OpenHands/extensions/blob/main/plugins/pr-review/workflows/pr-review-by-openhands.yml) - Example workflow
* [Composite Action](https://github.com/OpenHands/extensions/blob/main/plugins/pr-review/action.yml) - Reusable GitHub Action