> ## Documentation Index
> Fetch the complete documentation index at: https://allhandsai-tech-notes-llm-key-protection.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Automated Code Review

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

<Card title="View Example Plugin" icon="github" href="https://github.com/OpenHands/extensions/tree/main/plugins/pr-review">
  Check out the complete PR review plugin with ready-to-use code and configuration.
</Card>

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](/sdk/index) 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`**](https://github.com/OpenHands/extensions/tree/main/skills/code-review): Analyzes code for quality, security, data structures, and best practices with a focus on simplicity and pragmatism
   * [**`/github-pr-review`**](https://github.com/OpenHands/extensions/tree/main/skills/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

<Steps>
  <Step title="Copy the workflow file">
    Create `.github/workflows/pr-review-by-openhands.yml` in your repository:

    ```yaml theme={null}
    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 }}
    ```
  </Step>

  <Step title="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](/openhands/usage/llms/openhands-llms))
  </Step>

  <Step title="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`
  </Step>

  <Step title="Trigger a review">
    Open a PR and either:

    * Add the `review-this` label, OR
    * Request `openhands-agent` as a reviewer
  </Step>
</Steps>

## Composite Action

The workflow uses a reusable composite action from the Software Agent SDK 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                |
| -------------------- | --------------------------------------------------------------------------------------------------------------- | -------- | ---------------------- |
| `llm-model`          | LLM model to use                                                                                                | Yes      | -                      |
| `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`              |
| `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      | -                      |

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

## Customization

### Repository-Specific Review Guidelines

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

```markdown theme={null}
---
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]
```

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

<Note>
  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](https://github.com/OpenHands/software-agent-sdk/blob/main/.agents/skills/custom-codereview-guide.md) for a complete example.
</Note>

### Workflow Configuration

Customize the workflow by modifying the action inputs:

```yaml theme={null}
- 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:

```yaml theme={null}
# 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.

<Warning>
  **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](/sdk/guides/secrets) rather than environment variables, which prevents the agent from directly accessing these credentials during code execution.
</Warning>

## Example Reviews

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

| PR                                                                                              | Description                             | Review Highlights                                                             |
| ----------------------------------------------------------------------------------------------- | --------------------------------------- | ----------------------------------------------------------------------------- |
| [#1927](https://github.com/OpenHands/software-agent-sdk/pull/1927#pullrequestreview-3767493657) | Composite GitHub Action refactor        | Comprehensive review with 🔴 Critical, 🟠 Important, and 🟡 Suggestion labels |
| [#1916](https://github.com/OpenHands/software-agent-sdk/pull/1916#pullrequestreview-3758297071) | Add example for reconstructing messages | Critical issues flagged with clear explanations                               |
| [#1904](https://github.com/OpenHands/software-agent-sdk/pull/1904#pullrequestreview-3751821740) | Update code-review skill guidelines     | APPROVED review highlighting key strengths                                    |
| [#1889](https://github.com/OpenHands/software-agent-sdk/pull/1889#pullrequestreview-3747576245) | Fix tmux race condition                 | Technical review of concurrency fix with dual-lock strategy analysis          |

## Troubleshooting

<AccordionGroup>
  <Accordion title="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
  </Accordion>

  <Accordion title="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
  </Accordion>

  <Accordion title="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
  </Accordion>
</AccordionGroup>

## Automate This

You can schedule daily code reviews using [OpenHands Automations](/openhands/usage/automations/overview).
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](https://github.com/OpenHands/extensions/tree/main/plugins/pr-review)
as a GitHub Action instead.

## Related Resources

* [PR Review Plugin](https://github.com/OpenHands/extensions/tree/main/plugins/pr-review) - Full workflow example and agent script
* [Composite Action](https://github.com/OpenHands/extensions/blob/main/plugins/pr-review/action.yml) - Reusable GitHub Action for PR reviews
* [Software Agent SDK](/sdk/index) - Build your own AI-powered workflows
* [GitHub Integration](/openhands/usage/cloud/github-installation) - Set up GitHub integration for OpenHands Cloud
* [Skills Documentation](/overview/skills) - Learn more about OpenHands skills