External PR review
Colony can review human-authored PRs using the same engine it applies internally — deterministic checks followed by an LLM code review. For a conceptual overview of modes, trigger behavior, and what the review produces, see External PR Review.
Configure this feature from Standards → Settings › Review → External PR Review (/standards/settings, with no repository selected). The feature is off by default; you opt in by choosing a mode.
| Mode | Trigger | Best for |
|---|---|---|
off | No automatic reviews | Default — feature disabled |
on_request | A human comments /colony:review on the PR | Getting started; explicit opt-in per PR |
on_ready | PR is opened or transitions from draft to ready-for-review | Teams that want automatic review without auto-approval |
auto | Same triggers as on_ready; adds the option to post formal approvals | Fully automated review pipelines |
Configure in Colony Cloud
Section titled “Configure in Colony Cloud”- Open Standards → Settings in the Colony Cloud dashboard, with no repository selected.
- Open the Review section in the section nav and find the External PR Review subsection.
- Set the Mode dropdown to your preferred mode.
- Configure filters and exclusions as needed (see mode-specific sections below).
- Click Save at the bottom of the page.
Changes take effect on the next Worker heartbeat — no Worker restart is required.
Mode 1 — On request
Section titled “Mode 1 — On request”Set Mode to When requested (/colony:review comment) (on_request). Colony reviews a PR only when a human explicitly requests it by posting a slash command.
Trigger a review
Section titled “Trigger a review”- Open any non-draft, non-pipeline PR in your repository.
- Post
/colony:reviewas a comment on the PR. - Colony adds a reaction to acknowledge the request.
- Colony runs deterministic checks and the LLM review, then posts the results as a GitHub PR review.
By default, the /colony:review command is accepted from accounts with write access to the repository; anyone else gets a reply saying it was refused. If your organization sets commands.authorization to any, any human account can use it. Bot comments are ignored.
The author and label filters and the bot and draft exclusions also apply here. On a PR they exclude, /colony:review does nothing and Colony doesn’t reply.
Re-trigger after a push
Section titled “Re-trigger after a push”After you address feedback and push new commits, post /colony:review again to request a fresh review. Colony runs against the updated head commit, dismisses the previous review, and posts a new one.
Mode 2 — On ready
Section titled “Mode 2 — On ready”Set Mode to When a PR is opened or marked ready (on_ready). Colony automatically reviews a PR when it is opened as non-draft, or when it transitions from draft to ready-for-review.
Author filter
Section titled “Author filter”Use the Author filter field to limit automatic reviews to a specific allowlist of GitHub usernames. Enter usernames as comma-separated values (e.g., alice, bob, carol). Leave the field blank to allow all authors.
Label filter
Section titled “Label filter”Use the Label filter field to require specific labels on the PR before Colony reviews it. Enter label names as comma-separated values (e.g., review-please). All listed labels must be present — multiple labels use AND semantics. Leave the field blank to review without label requirements.
Bot and draft exclusions
Section titled “Bot and draft exclusions”Two checkboxes control which PR types are automatically skipped:
- Exclude bot-authored PRs — checked by default. Colony skips PRs authored by accounts GitHub reports as bots. Uncheck to include bot PRs.
- Exclude draft PRs — checked by default. Colony skips PRs in draft state. Uncheck to review drafts.
Re-review on push
Section titled “Re-review on push”When a contributor pushes new commits to a PR that Colony has already reviewed, Colony automatically re-reviews the updated PR. This only fires if Colony has previously reviewed that PR — new pushes to PRs that have never been reviewed do not trigger an unsolicited initial review.
Mode 3 — Auto
Section titled “Mode 3 — Auto”Set Mode to Automatically, with auto-approve (auto). Triggers are identical to on_ready — Colony reviews every eligible PR when it is opened or transitions to ready-for-review.
The Auto-approve checkbox only works in this mode. Check it to have Colony post a formal Approve review when the LLM verdict is APPROVE.
Automatic exclusions
Section titled “Automatic exclusions”Regardless of which mode you choose, Colony always skips the following:
- Colony’s own pipeline PRs — branches matching
colony/issue-Nand other agent branch patterns are never reviewed. - Colony’s bot username — PRs opened by Colony’s configured bot account are skipped.
- PRs carrying any
colony:label — pipeline-managed PRs are excluded.
These exclusions cannot be overridden from the form or any configuration field.
Configuration reference
Section titled “Configuration reference”The table below maps each underlying config field to its Colony Cloud form control and default value.
| Field | Default | Cloud form field | Description |
|---|---|---|---|
mode | off | Mode | off, on_request, on_ready, or auto |
author_filter | (all authors) | Author filter | Comma-separated GitHub usernames eligible for review |
label_filter | (no requirement) | Label filter | All listed labels must be present (AND semantics) |
exclude_bots | enabled | Exclude bot-authored PRs | Skip PRs authored by accounts GitHub reports as bots |
exclude_drafts | enabled | Exclude draft PRs | Skip PRs in draft state |
auto_approve | disabled | Auto-approve | In auto mode, post a formal Approve on an APPROVE verdict |
Per-repository overrides are not configurable from Colony Cloud — contact support if you need different external review modes per repository within the same organization.