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 Settings → Pipeline → Review → External PR Review. The feature is off by default; you opt in by choosing a mode.

Modes

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 as on_ready; the auto-approve intent flag is available	Fully automated review pipelines

Configure in Colony Cloud

1. Open Settings → Pipeline in the Colony Cloud dashboard.
2. Scroll to the Review section and locate the External PR Review subsection.
3. Set the Mode dropdown to your preferred mode.
4. Configure filters and exclusions as needed (see mode-specific sections below).
5. 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

Set Mode to on_request. Colony reviews a PR only when a human explicitly requests it by posting a slash command.

Trigger a review

1. Open any non-draft, non-pipeline PR in your repository.
2. Post /colony:review as a comment on the PR.
3. Colony adds a reaction to acknowledge the request.
4. Colony runs deterministic checks and the LLM review, then posts the results as a GitHub PR review.

The /colony:review command is accepted from any human account. Bot comments are ignored.

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

Set Mode to 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

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

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

Two checkboxes control which PR types are automatically skipped:

• Exclude bot-authored PRs — checked by default. Colony skips PRs authored by bot accounts (any account with [bot] in its GitHub username). Uncheck to include bot PRs.
• Exclude draft PRs — checked by default. Colony skips PRs in draft state. Uncheck to review drafts.

Note

The bot exclusion applies to the PR author’s GitHub username, not to the content of the PR. A human-authored PR that touches bot-generated files is not excluded.

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

Set Mode to 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 (mode: auto only) checkbox becomes meaningful with this mode. Check it to record an auto-approve intent in task metadata.

Caution

The auto-approve flag is recorded as task metadata and is reserved for future use. Colony posts a formal GitHub Approve review event when the LLM verdict is APPROVE, and a Request Changes event when the verdict is REQUEST_CHANGES. This behavior is consistent across all three modes and is not gated on the auto-approve flag. Checking the box today has no effect on review outcomes.

Automatic exclusions

Regardless of which mode you choose, Colony always skips the following:

• Colony’s own pipeline PRs — branches matching colony/issue-N and 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

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 with [bot] in their username
exclude_drafts	enabled	Exclude draft PRs	Skip PRs in draft state
auto_approve	disabled	Auto-approve (mode: auto only)	Recorded as task metadata; reserved for future use

Per-repository overrides are not configurable from Colony Cloud — contact support if you need different external review modes per repository within the same organization.