Choose Your Path

Colony can implement issues, review human-authored pull requests, propose repository improvements, and run a configurable delivery pipeline. Choose an outcome first; deployment and configuration decisions follow from it.

Note

If you are deciding whether Colony fits your environment, begin with Capabilities & Limitations. It distinguishes current behavior from features that are conditional, deployment-specific, or unavailable.

Evaluate Colony and choose a deployment

Use this path when you have not yet selected Colony Cloud or a self-hosted installation.

1. Read Core Concepts to understand the issue-to-PR model and the roles Colony automates.
2. Compare Capabilities & Limitations, paying particular attention to code-host support, Worker placement, operational ownership, and external PR review.
3. Choose Colony Cloud for a managed GitHub control plane, or Self-Host Colony when you need to operate Colony yourself or use Azure DevOps.
4. Confirm that the target repository, provider, authentication model, and required review policy are supported before installing anything.

Done when: you can name the deployment, provider, identity model, and first repository you will use.

Implement an issue

Use this path when you want Colony to take bounded work from an issue to a reviewed or merged pull request.

1. Follow Go from Zero to First Autonomous Merge. Azure DevOps users should first connect Azure DevOps.
2. Set a conservative intake policy with Configure Issue Intake and Workflow Routing.
3. Describe a small, verifiable outcome using Writing for Colony.
4. Decide who may approve and merge with Configure Merge Policy and Branch Protection.
5. Follow the issue through The Workflow and verify the diff, checks, and final provider state.

Done when: the first issue has produced a pull request whose checks and acceptance outcome you have reviewed, and it has either merged or reached the intended human gate.

Review human-authored pull requests

Use this path when your team writes the code and Colony should provide an additional review.

1. Confirm that the repository is on GitHub. Automatic external PR review is not available for Azure DevOps.
2. Set up External PR Review in manual mode for the first pull request.
3. Align deterministic checks and repository expectations with Build and Maintain Repository Conventions.
4. Decide whether Colony’s verdict is advisory or required under Configure Merge Policy and Branch Protection.
5. Enable automatic review only after author filters, draft behavior, and review publication match your policy.

Done when: an eligible human-authored PR receives the expected checks, findings, and GitHub review verdict without entering Colony’s implementation pipeline.

Improve a repository proactively

Use this path when you want Colony to propose work instead of waiting for a normal issue.

1. Read Strategy and Self-Improvement to separate strategic direction from recurring improvement tracks.
2. Roll Out Self-Improvement Tracks with one disabled, narrowly scoped track and a reviewed prompt version.
3. Enable the track, inspect its evidence and candidate slate, and select work only when it is worthwhile.
4. Monitor Worker capacity and cost using Operate and Scale Workers and Tune Model Routing and Cost Caps.

Done when: one selected candidate has completed the normal pipeline and you have evaluated both the proposal quality and implementation outcome.

Adapt Colony to a repository or workflow

Use this path when the default setup does not match the repository’s language, checks, architecture, or delivery process.

1. For non-TypeScript stacks, Onboard a Non-TypeScript Repository and prove setup in a clean worktree.
2. Build and Maintain Repository Conventions for facts agents should not infer.
3. Choose intake and a built-in workflow with Configure Issue Intake and Workflow Routing.
4. If a built-in workflow cannot express the required states and gates, Author and Register a Custom Workflow and observe the documented runtime-selection limits.
5. Tune model selection only after the deterministic environment and workflow are correct.

Done when: a clean Worker can reproduce setup and checks, new issues pin the intended workflow, and repository-specific constraints are versioned with the code.

Operate, scale, and recover

Use this path when you own reliability for an active Colony deployment.

1. Establish normal Worker health, queue depth, and throughput with Operate and Scale Workers.
2. Validate provider delivery and permissions with Troubleshoot Webhooks and Provider Permissions.
3. Learn how grouped work behaves with Operate Epics, Subtasks, and Dependencies.
4. For an individual delay, Triage a Stuck Issue. For an exhausted transition, Recover a Dead-Lettered Issue.
5. Schedule credential rotation and, for self-hosted installations, tested backup, upgrade, and rollback procedures.

Done when: you can distinguish healthy waits from failures, drain or replace capacity safely, recover a failed transition, and restore the deployment from a tested backup.

Browse by area

Concepts Understand Colony's shared mental models and lifecycle.

Guides Complete end-to-end operational tasks.

Self-Host Install and operate Colony on your own infrastructure.

Colony Cloud Use the managed control plane and dashboard.