> ## 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. # Automated Code Review > Set up automated PR reviews using OpenHands and the Software Agent SDK 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](/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 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 }} ``` 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)) 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` Open a PR and either: * Add the `review-this` label, OR * Request `openhands-agent` as a reviewer ### In a Conversation You can also trigger a code review manually in any OpenHands conversation. First, install the skill: ``` /add-skill https://github.com/OpenHands/extensions/tree/main/skills/code-review ``` Then invoke it: ``` /codereview ``` The agent will ask for the PR to review, or you can provide context directly: ``` /codereview β€” Please review PR #123 on my-org/my-repo. Focus on the new authentication middleware. ``` ## 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: ```bash theme={null} codex login --device-auth codex login status ``` Then create a base64-encoded secret from the generated auth file: ```bash theme={null} # 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: ```yaml theme={null} 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`: ```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] ``` **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](https://github.com/OpenHands/software-agent-sdk/blob/main/.agents/skills/custom-codereview-guide.md) for a complete example. ### 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. **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. ## 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 * 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 * 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 * Large PRs may take longer to analyze * Consider splitting large PRs into smaller ones * Check if the LLM API is experiencing delays ## Automate This There are two ways to automate PR reviews with OpenHands: as a **GitHub Action** (per-repo) or as an **OpenHands Automation** (org-wide, event-driven). Choose the approach that fits your needs, or use both. ### Option A: GitHub Action (Per-Repo) Use the [pr-review plugin](https://github.com/OpenHands/extensions/tree/main/plugins/pr-review) as a GitHub Actions workflow. Copy the [example workflow](https://github.com/OpenHands/extensions/blob/main/plugins/pr-review/workflows/pr-review-by-openhands.yml) into `.github/workflows/pr-review.yml` in your repository, add your `LLM_API_KEY` to **Settings β†’ Secrets and variables β†’ Actions**, and customize the trigger conditions and model as needed. See the [action.yml](https://github.com/OpenHands/extensions/blob/main/plugins/pr-review/action.yml) for all available inputs (`llm-model`, `llm-base-url`, `use-sub-agents`, `require-evidence`, and more). **When to use this:** You want per-repo control, need to integrate with existing CI checks, or want to pin specific action versions per repository. ### Option B: OpenHands Automation (Org-Wide) Before setting up an event-driven automation, complete the one-time [prerequisites for GitHub event automations](/openhands/usage/automations/event-automations#prerequisites-for-github-event-automations) β€” install the GitHub App, create a team org, and claim your GitHub organization. Without these steps, GitHub events will silently never arrive. [OpenHands Automations](/openhands/usage/automations/overview) is an event-triggered automation system that replaces per-repo GitHub Actions workflows. You define the trigger once and it covers all repositories matching your filter β€” no per-repo workflow files needed. It also leverages the full OpenHands runtime (browser, tools, sandbox), which GitHub Actions cannot. **When to use this:** You want a single configuration that covers all repos in your org, or you need the full OpenHands runtime for more advanced review workflows. #### Prerequisites: Bot Account For org-level automations, you should create a dedicated **bot account** (a separate GitHub user) and add it to your [OpenHands organization](/openhands/usage/cloud/organizations/overview). The bot account is the identity that will approve pull requests, request changes, and post review comments β€” keeping automated actions separate from human activity. Team members can then request this bot as a reviewer to trigger on-demand reviews. #### Setup: Create the Automation via Prompt Log in to [OpenHands Cloud](https://app.all-hands.dev) as your bot account (or under your team org) and send the following prompt in a new conversation. Replace the placeholders with your values: * `YOUR_ORG` β€” your GitHub organization name (e.g., `mycompany`) * `YOUR_BOT_LOGIN` β€” the GitHub username of your bot account (e.g., `mycompany-bot`) ```` Create an OpenHands Cloud automation using the Plugin Preset with the following configuration: **Name:** PR Review: YOUR_ORG/* (ready for review, review-this, or reviewer requested) **Plugin:** github:OpenHands/extensions (repo_path: plugins/pr-review) **Trigger events:** - pull_request.opened - pull_request.ready_for_review - pull_request.review_requested - pull_request.labeled **Filter:** ``` glob(repository.full_name, 'YOUR_ORG/*') && ( label.name == 'review-this' || requested_reviewer.login == 'YOUR_BOT_LOGIN' || (!label && !requested_reviewer && pull_request.author_association != 'FIRST_TIME_CONTRIBUTOR' && pull_request.author_association != 'FIRST_TIMER' && pull_request.author_association != 'NONE' && !pull_request.draft) ) ``` **Timeout:** 600 seconds **Prompt (use this exactly):** ``` Before starting the code review, complete these steps in order: Step 1 β€” Build the session URL. Run this in terminal: SESSION_URL="${AUTOMATION_SESSION_URL:-${AUTOMATION_API_URL:-https://app.all-hands.dev}}" echo "SESSION_URL=${SESSION_URL}" Step 2 β€” Extract PR info from the event payload: PR_NUMBER=$(echo "$AUTOMATION_EVENT_PAYLOAD" | python3 -c "import sys,json; p=json.load(sys.stdin); print(p['pull_request']['number'])") REPO=$(echo "$AUTOMATION_EVENT_PAYLOAD" | python3 -c "import sys,json; p=json.load(sys.stdin); print(p['repository']['full_name'])") Step 3 β€” Post a progress comment and save the comment ID: COMMENT_ID=$(curl -s -X POST \ -H "Authorization: Bearer $GITHUB_TOKEN" \ -H "Accept: application/vnd.github+json" \ "https://api.github.com/repos/$REPO/issues/$PR_NUMBER/comments" \ -d "{\"body\": \"πŸ” **Review in progress…**\\n\\nWe are performing the review through OpenHands Cloud Automation. You can log in and [view the conversation here](${SESSION_URL}).\"}" \ | python3 -c "import sys,json; print(json.load(sys.stdin)['id'])") Step 4 β€” /codereview and /github-pr-review Review the pull request using the pr-review plugin. Post a comprehensive code review on GitHub with inline comments on specific changed lines where appropriate, and a concise overall summary. Avoid duplicating existing unresolved review comments. When submitting the review, choose the appropriate event type: - Use "event": "APPROVE" when the PR is ready to merge with no blocking issues (minor suggestions are fine) - Use "event": "REQUEST_CHANGES" when there are blocking issues that must be fixed before merging - Use "event": "COMMENT" only when you need more information or are providing an informational review without a clear verdict At the end of the top-level review body include exactly: _This review was generated by an AI agent (OpenHands) on behalf of the user through OpenHands Automation. [View conversation](${SESSION_URL})_ Step 5 β€” After the review is posted, update the progress comment: curl -s -X PATCH \ -H "Authorization: Bearer $GITHUB_TOKEN" \ -H "Accept: application/vnd.github+json" \ "https://api.github.com/repos/$REPO/issues/comments/$COMMENT_ID" \ -d "{\"body\": \"βœ… **Review complete.**\\n\\nThis review was performed through OpenHands Cloud Automation. You can log in and [view the conversation here](${SESSION_URL}).\"}" ``` ```` **Team review requests:** The `requested_reviewer` field is only populated for individual reviewer requests. When a *team* is requested as reviewer, GitHub uses `requested_team` instead. To also match team requests, add `|| requested_team.slug == 'YOUR_TEAM_SLUG'` to the filter. **How `!label` works:** JMESPath treats absent fields as `null`, and `!null` evaluates to `true`. This means the third branch fires for `opened` and `ready_for_review` events (which have no `label` or `requested_reviewer` in the payload), while correctly staying silent for `labeled` and `review_requested` events where those fields are set. #### What This Produces When the automation is created and a qualifying PR event occurs, the bot will: 1. **Post a progress comment** on the PR: "πŸ” Review in progress…" with a link to the live conversation 2. **Run the pr-review plugin** which analyzes the diff and posts a structured code review with inline comments β€” approving clean PRs, requesting changes when there are blocking issues, or leaving an informational comment when the verdict is unclear 3. **Update the progress comment** to "βœ… Review complete." with the conversation link The automation triggers on four conditions: * **`opened`** β€” when a new non-draft PR is created (for established contributors only) * **`ready_for_review`** β€” when a draft PR is marked ready (for established contributors only) * **`review_requested`** β€” when your bot account is requested as a reviewer. This is the primary way team members trigger an on-demand review β€” they simply request the bot from the PR's "Reviewers" sidebar. The bot then posts its review under its own GitHub identity, so approvals and change requests come from a clear, dedicated account. * **`labeled`** β€” when the `review-this` label is added to any PR The automation does not re-run when new commits are pushed to an existing PR (`pull_request.synchronize` is intentionally excluded to avoid noisy re-reviews). To request a follow-up review after addressing feedback, re-add the `review-this` label or re-request the reviewer. The `$AUTOMATION_SESSION_URL` variable is injected by the automation runtime and resolves to a direct link to the conversation (e.g., `https://app.all-hands.dev/conversations/{uuid}`). The prompt includes fallbacks (`$AUTOMATION_API_URL`, then the default app URL) for environments where the variable is not yet available. The `$AUTOMATION_EVENT_PAYLOAD` variable contains the full GitHub webhook event as JSON. The `$GITHUB_TOKEN` (from the configured GitHub integration) is also automatically available. No additional configuration is needed for any of these variables. #### Single-Repo vs Org-Wide The prompt above uses `glob(repository.full_name, 'YOUR_ORG/*')` to cover **all repos** in your org. To target a single repo instead, replace the filter's first condition: ``` repository.full_name == 'YOUR_ORG/YOUR_REPO' && ( label.name == 'review-this' || requested_reviewer.login == 'YOUR_BOT_LOGIN' || (!label && !requested_reviewer && pull_request.author_association != 'FIRST_TIME_CONTRIBUTOR' && pull_request.author_association != 'FIRST_TIMER' && pull_request.author_association != 'NONE' && !pull_request.draft) ) ``` The `review-this` label and `requested_reviewer` branches do not exclude draft PRs β€” labeling a draft or requesting the bot on a draft will still fire the automation. This is intentional: explicit review requests should be honored regardless of draft status. #### Testing After creating the automation: 1. Add the `review-this` label to any open PR in a covered repo β€” this is the most reliable test since it works regardless of author history (you may need to [create the label](https://docs.github.com/en/issues/using-labels-and-milestones-to-track-work/managing-labels#creating-a-label) in your repo first if it doesn't exist) 2. Alternatively, request your bot as a reviewer on any PR, or open a new non-draft PR (note: the auto-trigger on `opened` requires the PR author to already have contributor history in that specific repo β€” `FIRST_TIME_CONTRIBUTOR`, `FIRST_TIMER`, and `NONE` associations are excluded) 3. Watch for the "πŸ” Review in progress…" comment β€” it should appear within a few seconds 4. The full review will typically follow within a few minutes, depending on PR size ## 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