GitHub Labels

Reference for every GitHub label Colony creates and consumes — state projections, flag labels, and the small set of labels operators can set directly to control the pipeline.

See also: Slash Command Reference for the primary operator control surface, Monitor Dashboard for the pipeline state glossary these labels project, and Configuration Reference for the labels.prefix and commands.root options.

Postgres Is the Authority

Postgres is the source of truth for pipeline state. GitHub labels are a write-only projection of that state, kept in sync by the outbox drainer. Editing a colony:<state> label directly does not change the issue’s state in Postgres — the next label sync will overwrite your edit with whatever Postgres says is authoritative, and in the meantime the pipeline continues to act on the real (Postgres) state, not the label you set.

To control an in-flight issue, use a slash command (e.g. /colony:retry, /colony:state <target-state>) or the colony CLI / MCP tools instead of editing labels. The exceptions — labels the sprint-master treats as inbound commands rather than projections — are documented below in Operator Command Labels.

State Projection Labels

Every non-unlabeled pipeline state is projected onto GitHub as a colony:<state> label. These labels are write-only — Colony sets them to reflect Postgres state; do not edit them by hand. Descriptions are sourced from PIPELINE_STATE_GLOSSARY in packages/dashboard/src/glossary.ts (see Monitor Dashboard — Pipeline State Reference for the canonical copy). unlabeled has no corresponding label — an issue with no colony: label is simply untracked.

State	Label	Description
`new`	`colony:new`	Issue has been enqueued and is awaiting analysis.
`planning`	`colony:planning`	Epic is being decomposed into subtasks by the planner.
`analyzing`	`colony:analyzing`	Issue is being analyzed to produce an implementation plan.
`needs-clarification`	`colony:needs-clarification`	Analyzer could not determine intent; waiting for the author to clarify.
`ready-for-dev`	`colony:ready-for-dev`	Analysis complete; issue is queued for implementation.
`dependency-blocked`	`colony:dependency-blocked`	Issue is waiting for one or more upstream issues to complete.
`failure-blocked`	`colony:failure-blocked`	Issue hit a hard block (repeated failures, cost cap, etc.) and needs operator action.
`changes-requested`	`colony:changes-requested`	PR reviewer requested changes; developer will revise and resubmit.
`in-review`	`colony:in-review`	Pull request is open and undergoing automated or human review.
`merge-pending`	`colony:merge-pending`	PR has passed review and is queued for merge.
`human-review-ready`	`colony:human-review-ready`	Automated checks passed; PR is ready for a human reviewer.
`waiting-for-subtasks`	`colony:waiting-for-subtasks`	Epic is waiting for all child subtasks to reach Done before it can proceed.
`done`	`colony:done`	Issue is complete; pull request has been merged.
`paused`	`colony:paused`	Issue processing is suspended by an operator; resumes when unpaused.

colony:paused is dual-purpose: it is both the state projection for the paused state and one of the labels operators can set directly to pause an issue — see Operator Command Labels.

Flag Labels

Flag labels are independent of the state machine — they mark a condition alongside whatever state label is currently set, rather than replacing it.

Label	Constant	Meaning
`colony:blocked`	`BLOCKED_LABEL`	Issue is blocked and needs operator attention (see the Blocked tab in the dashboard).
`colony:paused`	`PAUSED_LABEL`	Issue processing is suspended. Also an operator-settable command label — see below.
`colony:active`	`ACTIVE_LABEL`	Issue currently has an in-flight worker task.
`colony:epic`	`EPIC_LABEL`	Issue has been decomposed into sub-issues via `/colony:decompose` or planning.
`colony:needs-human`	`NEEDS_HUMAN_LABEL`	Escalation marker — the reviewer, merger, analyzer, or the worker’s budget enforcement determined the issue needs direct human attention.
`colony:needs-input`	`NEEDS_INPUT_LABEL`	Colony needs additional information from a human before it can proceed.
`colony:no-work-needed`	`NO_WORK_NEEDED_LABEL`	An agent determined the issue requires no code change.
`colony:stale`	`STALE_LABEL`	Issue has been idle past the configured staleness threshold.
`colony:ignore`	`IGNORE_LABEL`	Opts an issue out of automatic intake. Also an operator-settable command label — see below.
`colony:self-improvement`	`SELF_IMPROVEMENT_LABEL`	Issue was generated by Colony’s self-improvement loop rather than a human reporter.
`colony:alert`	`alertLabel()`	Applied by `GitHubIssueAlertChannel` to issues it creates for routed alerts (see `packages/core/src/alerting.ts`). Internal — you may see it on issues opened by Colony’s own alerting, not on your own issues.
`colony:digest`	`digestLabel()`	Applied by `GitHubIssueDigestChannel` to the daily and weekly reliability digest issues it creates (see `packages/monitor/src/digest-channels.ts`). Internal, same as `colony:alert`.
`colony:doctor-probe`	`doctorProbeLabel()`	Created and immediately deleted by `colony doctor`’s write-access probe; transient, never left on an issue or PR.

Self-improvement issues are further tagged with a per-track label in the colony:si-<track> namespace (e.g. colony:si-code-quality), computed by siTrackLabelNamespace(). The concrete set of tracks — and their label suffixes — is operator-configured via self_improvement.tracks[].label, so this namespace is provisioned alongside the flag labels above rather than being a fixed list.

Operator Command Labels

These are the only labels operators should set directly. The sprint-master treats them as inbound commands, not as projections of Postgres state — every other colony: label is projection output and should be left alone.

Label	Constant	Effect
`colony:enqueue`	`ENQUEUE_LABEL`	Seeds a new, untracked issue into the Colony pipeline — the same effect as commenting `/colony:enqueue`.
`colony:paused`	`PAUSED_LABEL`	Toggles pause/resume for an in-flight issue — the same effect as `/colony:pause` and `/colony:resume`.
`colony:ignore`	`IGNORE_LABEL`	Opts an untracked issue out of automatic intake — the sprint-master skips any unlabeled issue carrying this label rather than enqueueing it, whether intake mode is `tagged` or `all`.

Example — add an issue to the pipeline by label instead of slash command:

gh issue edit 123 --add-label colony:enqueue

Example — pause an in-flight issue, then resume it later:

gh issue edit 123 --add-label colony:paused
gh issue edit 123 --remove-label colony:paused

Example — opt an issue out of automatic intake:

gh issue edit 123 --add-label colony:ignore

Priority Label

colony:priority (PRIORITY_LABEL, produced by priorityLabel()) is a reserved constant in the label vocabulary — Colony does not currently apply it to any issue. Manual scheduling priority is set with /colony:priority <high|normal|low>, which writes directly to the manual_priority column in Postgres and posts an acknowledgment comment; it does not add, remove, or otherwise touch any GitHub label. If you see colony:priority referenced elsewhere, treat it as unused rather than as a live projection.

Customizing the Label Prefix

labels.prefix (default 'colony') rewrites the colony: domain across every label in this document — state labels, flag labels, and the operator command labels. See Configuration Reference — labels for the full option reference and the behavior when changing the prefix on a repo with existing issues.

labels.prefix is independent of commands.root. commands.root only changes the slash-command keyword (/colony:retry → /pipeline:retry); it does not affect GitHub labels. Renaming labels requires labels.prefix specifically — see Configuration Reference — commands for that caveat spelled out in full.