Skip to content
Colony Docs

Operator

The Operator owns the running system: configuration, provider credentials, repository registration, conventions, Worker availability, observability, and recovery. This is a responsibility model rather than a Colony permission.

Configuration and conventions are different

Section titled “Configuration and conventions are different”

For self-hosted Colony, runtime behavior is configured in colony.config.yaml. It covers provider access, repositories, executors, review checks, merge behavior, budgets, commands, Workers, and optional subsystems. Colony Cloud exposes supported settings through its application and service configuration. Use the Configuration Schema for exact fields and defaults.

The repository file .colony/conventions.md is prompt guidance for agents. Use it to describe the stack, architecture, test practices, naming, forbidden patterns, and review priorities. It is not the runtime configuration file and it does not override workflow state, permissions, checks, or merge policy. Colony loads the repository-level file; there is no documented nearest-folder override mechanism.

Capacity

Section titled “Capacity”

Each Worker claims one compatible task at a time. Adding eligible Workers can increase concurrency when the queue contains independent runnable tasks, but it does not repair a single failed task, remove a dependency, or make an incompatible Worker eligible.

Use the deployment’s task, queue, and Worker telemetry to distinguish queued work from blocked or failed work before changing capacity. Cloud allocation and self-hosted process count are deployment-specific; there is no universal “correct” pool-size formula.

Intervene

Section titled “Intervene”

Start with the issue’s workflow state, latest task result, attempts, and provider checks:

  • needs-clarification needs a human reply to the analyzer’s question
  • dependency-blocked waits for the recorded blocking condition to clear
  • failure-blocked needs diagnosis, retry, or another explicit recovery action
  • human-review-ready needs human handling or reflects disabled automatic merge
  • paused remains stopped until resumed or cancelled

The Mayor reconciles many transient inconsistencies and retries work according to configuration. It cannot correct an ambiguous issue, unavailable credentials, a persistent executor failure, an exhausted cost cap, or a merge the provider refuses.

Recover deliberately

Section titled “Recover deliberately”

Slash commands request audited, workflow-validated actions. Common examples include retrying the current stage, pausing or resuming one issue, rerunning analysis or review, sending feedback to development, or cancelling work. Some commands are valid only from particular states, and custom workflows can change those constraints.

Use Slash Commands as the canonical catalog. In particular:

  • /colony:pause pauses the addressed issue; it is not a global, tenant, or repository freeze
  • /colony:cancel moves supported work to completion/cancellation handling; it does not erase the audit trail
  • /colony:reopen is supported only when the pinned workflow declares the transition
  • changing a projected state label is not a recovery action

For a release freeze or incident-wide stop, use provider branch protection and deployment controls appropriate to your environment. Colony does not expose a built-in global freeze-window abstraction.

Operational checklist

Section titled “Operational checklist”
  • validate provider and executor credentials
  • configure deterministic review commands explicitly
  • set cost and attempt limits appropriate to the repository
  • decide whether automatic merge is enabled
  • keep .colony/conventions.md accurate when repository-wide patterns change
  • alert on persistent failed tasks and unavailable Workers
  • preserve task and transition records when investigating incidents

Going deeper

Section titled “Going deeper”