External PR Review

Colony can review human-authored pull requests — PRs that are not part of its own pipeline — using the same review engine it applies to its own work: deterministic checks (build, test, lint) run in a real worktree, followed by an LLM code review that understands the repo’s conventions.

This is configured via review.external_prs in your Colony config.

Modes

There are three modes, ordered from safest to most aggressive:

Mode	Trigger	Best for
`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`, plus the `auto_approve` flag is available	Fully automated review pipelines

The feature is off by default (mode: off). You must opt in.

Mode 1 — On Request (Recommended Starting Point)

Enable by setting mode: on_request. Colony only reviews a PR when a human explicitly requests it.

review:
  external_prs:
    mode: on_request

How to trigger a review

Open any non-draft, non-pipeline PR in your repo.
Comment /colony:review 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.

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

Re-triggering a review

After you address feedback and push new commits, comment /colony:review again to request a fresh review. Colony will run against the updated head commit and post a new review, dismissing the previous one.

Mode 2 — On Ready

Colony automatically reviews a PR when it is opened (non-draft) or transitions from draft to ready-for-review.

review:
  external_prs:
    mode: on_ready

Filtering who gets reviewed

Use author_filter to limit automatic reviews to a specific allowlist of GitHub usernames. The default ['*'] means all authors are eligible.

review:
  external_prs:
    mode: on_ready
    author_filter: ['alice', 'bob', 'carol']

Use label_filter to require specific labels on the PR before reviewing. Multiple labels use AND semantics — all listed labels must be present.

review:
  external_prs:
    mode: on_ready
    label_filter: ['review-please']

Bot and draft exclusions

By default, Colony skips:

Draft PRs (exclude_drafts: true) — set to false to review drafts
Bot-authored PRs (exclude_bots: true) — set to false to review bot PRs

review:
  external_prs:
    mode: on_ready
    exclude_drafts: false # review drafts too

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 on PRs that have never been reviewed do not trigger an unsolicited initial review.

Mode 3 — Auto

Same as Mode 2 in terms of triggers — Colony reviews every eligible PR when it is opened or transitions to ready. The auto_approve config flag is only meaningful with this mode (Colony logs a startup warning if auto_approve: true is set without mode: auto).

review:
  external_prs:
    mode: auto
    auto_approve: true

Note: Colony posts a formal GitHub Approve review event whenever the LLM verdict is APPROVE, and a Request Changes event when the verdict is REQUEST_CHANGES. This behavior is the same across all three modes — it is determined solely by the LLM verdict and is not gated on auto_approve. The auto_approve flag is recorded as task metadata and validated at startup; it is reserved for future use.

Automatic Exclusions

Regardless of mode, Colony always skips:

Colony’s own pipeline PRs — branches matching colony/issue-N or other agent branch patterns are never reviewed
Colony’s bot username — PRs opened by Colony’s configured bot_username are skipped
PRs carrying any colony: label — pipeline-managed PRs are excluded

These exclusions cannot be overridden.

Per-Repo Overrides

In multi-repo deployments, you can set a global default and override it per repo:

# Global default — off for all repos
review:
  external_prs:
    mode: off

repos:
  - owner: myorg
    repo: my-app
    workspace:
      repo_dir: /repos/my-app
      base_dir: ~/.colony/workspaces/myorg/my-app
    review:
      external_prs:
        mode: on_request # only this repo gets external review

Each field set in the per-repo review.external_prs block overrides the corresponding global value; fields not set in the per-repo block fall back to the global review.external_prs value (or the built-in default if neither is set).

Configuration Reference

For full field documentation, see ExternalPrReviewConfig in the configuration reference.

Field	Default	Description
`mode`	`'off'`	`off`, `on_request`, `on_ready`, or `auto`
`author_filter`	`['*']`	Allowlist of GitHub usernames (`['*']` = all)
`label_filter`	`[]`	Require all listed labels (AND semantics)
`exclude_bots`	`true`	Skip bot-authored PRs
`exclude_drafts`	`true`	Skip draft PRs
`auto_approve`	`false`	Recorded as task metadata; validated to require `mode: auto` (startup warning otherwise). Reserved for future use