|
| 1 | +--- |
| 2 | +name: pr-review-agent |
| 3 | +description: Deploy or update the PR Review Agent on Omnara, an agent that reviews GitHub pull requests through Omnara's GitHub integration and leaves inline findings. Use when the user asks to deploy, set up, update, or remove the PR review agent. |
| 4 | +--- |
| 5 | + |
| 6 | +# Deploy the PR Review Agent |
| 7 | + |
| 8 | +You are setting up an Omnara agent for the user from `agent.yaml` in this |
| 9 | +folder. The goal: a GitHub App on the user's repositories that reviews pull |
| 10 | +requests the way they chose, and that the user has watched publish one |
| 11 | +review. |
| 12 | + |
| 13 | +The steps below are the usual path, with the exact commands. Skip anything |
| 14 | +that's already done (for example, the profile and integration exist and the |
| 15 | +user only wants a different trigger), and follow the user's lead if they want a |
| 16 | +different order. |
| 17 | + |
| 18 | +- Start from `agent.yaml` as written. If the user wants something different |
| 19 | + (the instruction, tools, or model), change it and tell them what you |
| 20 | + changed. |
| 21 | +- If a command fails, `npx omnara <command> --help` and |
| 22 | + [docs.omnara.com](https://docs.omnara.com) have the details. |
| 23 | +- Stop only where a step says to ask the user. Ask in a sentence or two of |
| 24 | + plain language, together with the next step's question if one comes right |
| 25 | + after, then end your turn and wait for the reply. |
| 26 | +- Where a step gives a default, use it without asking and say in a line what |
| 27 | + you picked, so the user can change it. |
| 28 | + |
| 29 | +The commands use the Omnara CLI (`npx omnara`); add `--json` to read IDs. |
| 30 | +They're a reference, not a requirement: the Omnara MCP tools, the |
| 31 | +[REST API](https://docs.omnara.com/api-reference/openapi.yaml), and the SDK work |
| 32 | +too, and the flags map directly to API fields. |
| 33 | + |
| 34 | +No GitHub token is needed. The GitHub integration's launcher gives each agent |
| 35 | +the pull request tools and Git credentials from the App's installation. |
| 36 | + |
| 37 | +## 1. Connect to Omnara |
| 38 | + |
| 39 | +Run `npx omnara whoami`. If you aren't logged in, run `npx omnara login` without |
| 40 | +piping its output, and keep it running: it waits until the user approves. It |
| 41 | +opens the approval page in the user's browser and prints the page's link and a |
| 42 | +code. Show the user both right away, since you may be on a different machine |
| 43 | +than their browser, and ask them to approve once the code matches. If the |
| 44 | +request expires, run it again. If login says the account has no organization |
| 45 | +yet, have the user create one at the link it prints. Then `npx omnara whoami` |
| 46 | +should succeed. |
| 47 | + |
| 48 | +Pick the org and project (`npx omnara whoami --json` lists orgs, |
| 49 | +`npx omnara projects list --org <org-id> --json` their projects): use them if |
| 50 | +there's one of each, otherwise the defaults from `npx omnara config` or the |
| 51 | +project named `Default`; ask only if there's still no clear choice. Save the |
| 52 | +choice with `npx omnara config --org <org-id> --project <project-id>`; later |
| 53 | +steps need the project ID. |
| 54 | + |
| 55 | +## 2. Choose how it works on GitHub |
| 56 | + |
| 57 | +Ask the user these in one message, with the defaults, so they can answer |
| 58 | +"defaults" or change only what they care about. Wait for the reply. |
| 59 | + |
| 60 | +1. **When it reviews**, which becomes the launcher's `trigger`. Default |
| 61 | + `both`: it reviews every new pull request opened by someone with write |
| 62 | + access, and anyone with write access can mention it on any pull request. |
| 63 | + The alternatives are `pull_request_opened` (new pull requests only) and |
| 64 | + `mention` (only when someone writes, say, "@acme-reviewer review this"). |
| 65 | + Each review runs its own agent and machine, so automatic reviews on a busy |
| 66 | + repository cost more than mentions. Pull requests from bots or people |
| 67 | + without write access never start one on their own. |
| 68 | +2. **New pushes.** Default: it stays quiet when commits land on a pull |
| 69 | + request it reviewed, until someone asks it to review again. The |
| 70 | + alternative is reviewing each push automatically, covering only the new |
| 71 | + commits. |
| 72 | +3. **Which repositories.** Default: the ones the user grants the App when |
| 73 | + installing it in step 5, so suggest granting only the repositories they |
| 74 | + want reviewed. |
| 75 | +4. **Which GitHub App.** Default: a new App just for reviews, named after the |
| 76 | + team (for example, "Acme Reviewer"), so its comments are clearly the |
| 77 | + reviewer's. If `npx omnara integrations list --json` shows another |
| 78 | + `github_pr` integration, such as the coding agent's, mention that it can |
| 79 | + launch only one profile, so pointing it at this agent takes it away from |
| 80 | + the other one. |
| 81 | + |
| 82 | +## 3. Pick the model and machine pool |
| 83 | + |
| 84 | +1. `npx omnara grant models list --json`: each item has `model.provider_config` |
| 85 | + and `model.name`. Use `anthropic/claude-opus-5.5` on `omnara-openrouter` if |
| 86 | + it's granted (`agent.yaml` runs it at high reasoning effort), otherwise the |
| 87 | + strongest coding model on the list. The choice gives `MODEL_PROVIDER_CONFIG` |
| 88 | + and `MODEL_NAME`. |
| 89 | +2. `npx omnara grant pools list --json`; each grant's `machine_pool.name` is a |
| 90 | + candidate `MACHINE_POOL`. Use `default-pool` if it's granted: its machines |
| 91 | + come with `git` and common language toolchains, so the agent can run tests |
| 92 | + to confirm a finding. Otherwise use the only pool, or ask if there are |
| 93 | + several. On a custom pool, the image needs `git` and an up-to-date |
| 94 | + `omnarad`, which supplies the Git credentials. If there are none, the agent |
| 95 | + can still review from the diff alone, which catches less: in step 4, |
| 96 | + delete the `machine_sources` block and the instruction's "Checking out the |
| 97 | + code" section, and tell the user. |
| 98 | + |
| 99 | +## 4. Create the agent |
| 100 | + |
| 101 | +1. Copy `agent.yaml` from this folder to `./pr-review-agent.yaml` in the |
| 102 | + current directory. If this folder isn't available locally, download |
| 103 | + https://raw.githubusercontent.com/omnara-ai/omnara/main/examples/pr-review-agent/agent.yaml |
| 104 | + instead. |
| 105 | +2. In the copy, replace every placeholder: |
| 106 | + |
| 107 | + | Placeholder | Value | |
| 108 | + | --- | --- | |
| 109 | + | `{{MODEL_PROVIDER_CONFIG}}` | from step 3 | |
| 110 | + | `{{MODEL_NAME}}` | from step 3 | |
| 111 | + | `{{MACHINE_POOL}}` | from step 3 | |
| 112 | + |
| 113 | + Then confirm nothing is left: `grep -n '{{' pr-review-agent.yaml` must |
| 114 | + print nothing. |
| 115 | +3. If the user wants every push reviewed, replace the instruction's paragraph |
| 116 | + that starts "When new commits are pushed" with: |
| 117 | + |
| 118 | + ```text |
| 119 | + When new commits are pushed, you're told the head changed. Review only |
| 120 | + what changed since your last review, as above, and publish it the same |
| 121 | + way. If the new commits don't change anything worth raising, post |
| 122 | + nothing. |
| 123 | + ``` |
| 124 | + |
| 125 | + As written, it focuses on correctness, security, breaking changes, and |
| 126 | + missing tests, and leaves at most 10 inline comments. If the user named |
| 127 | + anything else to check or skip, edit the instruction's Reviewing section; |
| 128 | + team conventions are better kept in the repository's `AGENTS.md` or |
| 129 | + `CONTRIBUTING.md`, which it already follows. |
| 130 | +4. Check for an existing profile: `npx omnara profiles list --name pr-review-agent --json`. |
| 131 | + - None: `npx omnara profiles create --name pr-review-agent --file ./pr-review-agent.yaml --json` |
| 132 | + - Exists: `npx omnara profiles update <agent-profile-id> --file ./pr-review-agent.yaml --json` |
| 133 | + |
| 134 | + If it rejects the reasoning effort, the chosen model doesn't support |
| 135 | + `high`: remove the `reasoning` block and retry. Note the profile `id`. |
| 136 | + |
| 137 | +## 5. Connect GitHub |
| 138 | + |
| 139 | +Set up the GitHub integration with the "GitHub pull requests" section of |
| 140 | +[`integrations.md`](../integrations.md) (read it from |
| 141 | +https://raw.githubusercontent.com/omnara-ai/omnara/main/examples/integrations.md |
| 142 | +if you don't have the repo). For this agent: |
| 143 | + |
| 144 | +- Name the integration `pr-review-agent-github`, and use the trigger from |
| 145 | + step 2 in its launcher, for example |
| 146 | + `{"launcher":{"trigger":"both","profile":"<agent-profile-id>"}}`. If a |
| 147 | + `github_pr` integration's `settings.launcher.profile` is already this |
| 148 | + profile, it was set up earlier under another name: reuse it, and update |
| 149 | + its launcher only if the trigger changed. If the user chose to reuse |
| 150 | + another agent's `github_pr` integration, update that one's launcher |
| 151 | + instead of creating a new one. |
| 152 | +- Suggest an App name with the team's name, such as "Acme Reviewer"; its slug |
| 153 | + (`acme-reviewer`) is how the team mentions it. Grant the repositories from |
| 154 | + step 2. |
| 155 | +- Skip the **Contents** write change. The App Omnara registers can already |
| 156 | + read code and post reviews, and a reviewer never pushes. Do have the user |
| 157 | + check the App's **Webhook URL**. |
| 158 | +- If the App's installation covers more repositories than should be |
| 159 | + reviewed, add `"repository_id":"<id>"` to `launcher`, the repository's |
| 160 | + numeric ID as a string (`gh api repos/<owner>/<name> --jq .id` prints it). |
| 161 | + The launcher takes one repository. |
| 162 | + |
| 163 | +## 6. Watch a first review |
| 164 | + |
| 165 | +Pick the test from the trigger: |
| 166 | + |
| 167 | +- With `mention` or `both`, have the user comment on an open pull request in |
| 168 | + one of the granted repositories: "@acme-reviewer review this", with their |
| 169 | + App's slug. |
| 170 | +- With `pull_request_opened`, have the user open a new pull request, even a |
| 171 | + small one. |
| 172 | + |
| 173 | +Omnara adds an 👀 reaction to a comment it accepted. The agent also shows up |
| 174 | +in the Omnara console ([app.omnara.com](https://app.omnara.com)), where the |
| 175 | +user can watch it read the diff and the code. A review takes a few minutes: the |
| 176 | +machine starts, clones the repository, and the agent reads around each |
| 177 | +change before it posts. If nothing happens after a couple of minutes, check |
| 178 | +the App's webhook URL and its **Advanced** tab on GitHub, which lists recent |
| 179 | +deliveries and their responses. |
| 180 | + |
| 181 | +Once the review is up, suggest the user reply to one of its comments to see |
| 182 | +it answer in the thread. |
| 183 | + |
| 184 | +## 7. Wrap up |
| 185 | + |
| 186 | +Summarize what you created: the profile, the integration, and the GitHub App, |
| 187 | +and how it's set to run (trigger, new pushes, repositories). Then tell the |
| 188 | +user: |
| 189 | + |
| 190 | +- **Change when it runs:** `npx omnara integrations update <integration-id>` |
| 191 | + with the whole `settings` object, or the **Pull requests** section on the |
| 192 | + integration's page in the dashboard. |
| 193 | +- **Change how it reviews, the model, or anything else:** ask a coding agent |
| 194 | + with this skill. It updates the profile in place, and the next review uses |
| 195 | + it. |
| 196 | +- **Remove it:** remove the integration (see "Removing" in `integrations.md`), |
| 197 | + then run `npx omnara profiles delete <agent-profile-id>`. Reviews it already |
| 198 | + posted stay on the pull requests. |
0 commit comments