Configure Merge Policy and Branch Protection

Colony can approve work, wait for required checks, and attempt a merge, but the code host remains the final authority. Configure Colony and provider policy together so a successful review cannot bypass a required gate—or wait forever on an impossible one.

Choose the first safe policy

Start with automatic merge off. Require Colony’s deterministic checks, inspect its review, then approve and merge the first few pull requests as a human. Enable automatic merge only after the repository consistently reaches the intended human gate.

Decision	Conservative starting point
Intake	Tagged only
Colony automatic merge	Off
Provider pull-request requirement	On
Required CI	The smallest stable set that protects the default branch
Review identity	Separate from the code-author identity
Epic final review	Human required

Configure Colony’s review and merge gates

Colony Cloud

1. Open the repository’s configuration in Colony Cloud.
2. Enter the exact GitHub check names Colony must observe before merge. A display label that does not match the check-run name never becomes satisfied.
3. Keep automatic merge disabled while validating the repository.
4. Confirm both the coder and operations GitHub Apps are installed when Colony should publish formal reviews and merge autonomously.
5. Save the configuration and test it with a small PR.

Self-Host

Configure the checks Colony runs itself and any provider checks it must wait for:

review:
  checks:
    test: npm test
    lint: npm run lint
  ci_required_checks:
    - ci/test
    - ci/lint
  auto_merge_on_approval: false

review.checks are shell commands executed in the review worktree. review.ci_required_checks are provider check names observed after the PR exists. Both must be correct; one does not replace the other.

Review settings hot-reload, including repo-level repos[].review overrides. Use config reload and inspect the applied keys before testing.

Configure distinct identities

GitHub and Azure DevOps prevent or constrain authors from approving their own pull requests. Use a coder identity for branches, commits, and PR creation, and an operations identity for review, issue transitions, and merge API calls.

• On GitHub, configure the coder App and a separate operations App. The coder identity still performs git push operations used by the Merger; the operations identity publishes the review and calls the merge API.
• On Azure DevOps, configure separate token_env and ops_token_env PATs belonging to different users when automatic approval is required.

If the operations identity is absent, Colony can still prepare the PR, but a human approval may be required even when auto_merge_on_approval is enabled.

Create or inspect branch protection

For self-hosted Colony, run:

colony init
colony check --stage credentials --stage repository --stage labels

On GitHub, colony init creates or verifies a ruleset for the configured workspace.branch when the token has administration permission. Set the actual default branch before running it. On Azure DevOps, Colony creates or recognizes a blocking minimum-reviewer policy for the default branch when the PAT has policy administration rights.

Then inspect the provider directly. Align these items:

• pull requests are required for the protected branch;
• the required check names match actual CI check runs;
• the operations identity may review and merge;
• the coder identity may create branches and push updates;
• merge method and stale-approval behavior match your team policy;
• no rule requires an approval that only the PR author can provide.

Note

colony init establishes a minimum viable policy. Organization-level rules, merge queues, deployment gates, signed-commit requirements, and custom branch patterns remain provider administration concerns.

Account for epic branches

When epic.use_feature_branches is enabled, subtasks can target epic/<issue> rather than the default branch. Ensure repository policy permits the coder identity to create and update epic/* branches. Decide separately whether subtask PRs may merge automatically and whether the final epic PR requires human review.

epic:
  use_feature_branches: true
  auto_merge_subtasks: true
  review:
    require_human_final_review: true

Epic configuration is startup-only; restart Workers after changing it.

Prove the complete gate

1. Open a small Colony-authored PR and confirm deterministic checks execute in a clean review worktree.
2. Confirm every configured provider check appears under its exact name and reaches a terminal result.
3. Verify the operations identity can publish a formal approval without being treated as the author.
4. With automatic merge still off, merge manually and confirm Colony reaches done.
5. Enable automatic merge, repeat with another small issue, and confirm Colony merges only after every required condition passes.

Diagnose a blocked merge

Symptom	Likely cause
Review approved but merge never starts	Automatic merge is off, an approval is still required, or the issue’s workflow routes to a human gate.
Required check never completes	Configured name does not match the provider check-run name, CI never triggered, or CI is waiting on another gate.
Provider rejects approval	Reviewer and author are the same identity or the operations identity lacks review permission.
Provider rejects merge	Branch protection, merge queue, stale branch, permissions, or unsupported merge method conflicts with Colony’s request.
Epic subtask cannot push	Policy or credentials do not permit updates to epic/*, or the branch is stale.

What next

• Set up External PR Review
• Operate Epics, Subtasks, and Dependencies
• Troubleshoot Webhooks and Provider Permissions