Guides

Use these guides for end-to-end operational tasks. Reference pages define individual fields and commands; guides show how to combine them safely.

Start and connect

Go from Zero to First Autonomous Merge Connect a GitHub repository, enqueue a small issue, and review its first Colony-authored pull request.

Connect Azure DevOps End to End Connect self-hosted Colony to Azure DevOps Repos, work items, policies, and service hooks.

Onboard a Non-TypeScript Repository Configure worktree setup, deterministic checks, and repository guidance for any stack.

Build and Maintain Repository Conventions Version durable architecture, setup, validation, and change-boundary guidance with the code.

Configure Issue Intake and Workflow Routing Control which new issues enter Colony and which workflow each issue pins.

Configure Merge Policy and Branch Protection Align Colony review and CI with provider identities, approvals, and branch rules.

Set up External PR Review Review eligible human-authored GitHub pull requests on request or automatically.

Author and Register a Custom Workflow Derive, validate, register, and safely roll out a versioned workflow definition.

Tune Model Routing and Cost Caps Route Claude tasks by work type and complexity, then set and verify spend limits.

Roll Out Self-Improvement Tracks Introduce one proactive improvement track, evaluate its candidates, and expand safely.

Operate Epics, Subtasks, and Dependencies Monitor grouped delivery, dependency edges, epic branches, and safe recovery.

Operate and Scale Workers Size capacity, drain or reclaim safely, and replace unhealthy Workers.

Troubleshoot Webhooks and Provider Permissions Follow provider events from delivery through authentication, intake, and task creation.

Triage a Stuck Issue Distinguish intentional waits from failures and choose the smallest workflow-valid intervention.

Recover a Dead-Lettered Issue Inspect, retry, or acknowledge a pipeline transition that could not complete.

Rotate Credentials Without Stopping the Pipeline Replace provider, LLM, Worker, database, and feed credentials with controlled handoffs.

Upgrade, Back Up, and Roll Back Self-Hosted Colony Back up durable state, drain safely, verify migrations, and restore a previous version.