> For the index of every page in Orbital's docs, read https://docs.beta.runorbital.dev/llms.txt.

# Review pull requests

> Start a review run each time someone opens a pull request

In this example you have an agent review every new pull request. You add the `review-pull-request` workflow to your library, then make a [trigger](/triggers/) rule that starts it when a pull request opens. The run reads the pull request and leaves one review comment.

About ten minutes to set up. After that, each review run starts within about a minute of a pull request opening.

```dot title="review-pull-request.dot"
digraph review_pull_request {
  graph [version="1", entry="review", description="Review one pull request and leave the review as comments, without changing, approving or merging it"]

  review [role="Reviewer", tools="read, shell", prompt_file="prompts/review-pull-request/review.md"]
  done [shape="Msquare", outcome="success"]

  review -> done
}
```

![review has one step, then done.](/review-pull-request.svg?v=86d090e8cf)

## Before you start

You need:

- the Triggers feature turned on: **Settings > Experimental features > Triggers**;
- a GitHub token that can read the repository and comment on its pull requests, from `gh auth login` or **Settings > GitHub**;
- the `gh` command on the machine that runs Orbital;
- a project whose primary folder is the repository;
- the workflow: [download the archive](/review-pull-request.zip).

## 1. Add the workflow

1. Unpack the archive into your workflow library, `~/.orbital/workflows/`. Keep every relative path.

2. Check it:

   ```sh
   orbital validate ~/.orbital/workflows/review-pull-request.dot
   ```

Every project now offers `review-pull-request`, and it shows on the **Workflows** page.

![The Workflows page listing workflows with their source, Clone and Export actions, and Import and New workflow buttons.](/screenshots/workflows-page.webp?v=991e5fde13)

*Workflows in your library show here for every project.*

The archive holds the workflow above and its prompt:

```md title="prompts/review-pull-request/review.md"
Review this pull request: {{ inputs.goal }}

Read the pull request with the GitHub command line, `gh`: its description, the tickets it names, its diff, its checks and the review comments already on it. Read the repository's instructions files, such as AGENTS.md or CLAUDE.md, and follow its review conventions.

Look for defects, missed requirements, missing tests and risks. For each finding, give the file and line, what is wrong, why it matters and the evidence. Do not report style a formatter would fix.

Leave one review on the pull request with `gh pr review --comment`, holding every finding. Never approve, request changes on, merge or close the pull request, and do not push commits or change any file. If you cannot read the pull request, say so and stop.

End with a short summary of the review you left, with the pull request's address.
```

## 2. Understand what the agent can do

The step runs as the Reviewer role, but `tools="read, shell"` replaces the role's Full access. The step can read files and run commands, because it needs `gh` to read the pull request and post the review. It has no Change files, no web and no connected services. The workflow makes no worktree. Its prompt tells it never to approve, merge or change anything.

The pull request's title, description and diff come from whoever opened it. The agent reads them, so text in them can try to steer it. The prompt tells the agent not to change or push anything, but a prompt is only a request: [tool access, not the prompt, enforces limits](/roles/#permissions). Taking away Change files stops the agent editing files directly. It can still run commands. So the rule in the next step should also start runs only for pull requests from people you trust.

## 3. Make the rule

1. Open **Triggers** in the sidebar and choose the ready-made rule "Review every new pull request". It fills in:

   - source: GitHub, for pull requests that are opened;
   - action: Starts a run;
   - goal: `Review {{ url }}: {{ title }}`.

![The New rule dialog set to GitHub pull requests, with the event A pull request is opened.](/screenshots/trigger-rule-github.webp?v=c4800c5727)

*The ready-made rule listens for opened pull requests.*

2. Choose the project and the `review-pull-request` workflow.

3. Limit it to people you trust. Under **Only if**, add "Author's team is any of" and pick a team of your organisation, written as `organisation/team`, such as `acme/engineering`. The rule then starts runs only for pull requests that team's members open, not for one from a stranger on a public repository. Add more conditions if you need them. For example, "Target branch is any of `main`", or leave out draft pull requests.

4. Choose **Try it and save**. Orbital shows what the rule would have done over the last seven days. Saving turns the rule on.

:::caution
Once saved, the rule starts runs on its own, with no one choosing **Start run**. Each opened pull request that passes **Only if** starts one.
:::

## 4. Open a pull request

When someone opens a pull request, the rule starts a run within about a minute. The run's goal holds the pull request's address and title.

The rules list shows when each rule last checked and what it did, such as "Started a run".

![The Triggers page listing rules with their source, an on or off switch, what each does and its recent firings.](/screenshots/triggers-page.webp?v=5fe1ad8f4b)

*Each rule's line shows its last check and what it did.*

## What you get

The review appears on the pull request as a comment. The run's last message in the **Session** tab summarises it.

## Keep it under control

Each opened pull request starts one run, and each run takes a run slot while it works. Keep **Concurrent runs** in mind, and narrow the rule with conditions on a busy repository. See [The run queue](/runs/queue/).

A rule can also stop, pause or message the runs that a trigger started for the same pull request. For example, a second rule on "closed" with the action **Stops runs** ends a review that is no longer needed.

## Related

- [Triggers](/triggers/): what a rule watches and what it can do to runs
- [Make a trigger rule](/triggers/make-a-rule/): build a rule of your own step by step
- [Settings](/reference/settings/#experimental-features): turn on the Triggers feature
- [The run queue](/runs/queue/): how many runs work at once