GitHub Labels
GitHub Labels
Section titled “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
Section titled “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
Section titled “State Projection Labels”Every pipeline state except unlabeled and dependency-blocked 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.
The table below is generated from the builtin workflow (packages/workflow-engine/src/builtin/colony-default.yaml) by npm run docs:workflow; do not edit it by hand.
Its descriptions are the workflow’s own state descriptions. The
Monitor Dashboard — Pipeline State Reference shows the
dashboard’s fallback glossary (PIPELINE_STATE_GLOSSARY), which is worded separately and is more
precise for some states: planning is epic decomposition into subtasks, and ready-for-dev follows
analysis (not planning) for a regular issue. unlabeled and dependency-blocked have no corresponding state label (both shown as —
below). An issue with no colony: label is simply untracked; a dependency-blocked issue shows as
colony:blocked plus GitHub’s native “blocked by #N” relationship. The legacy
colony:dependency-blocked label is no longer projected; label-sync removes it if it finds one.
| State | Label | Type | Description | Transitions to | Recovery |
|---|---|---|---|---|---|
unlabeled | — | awaiting-human | This issue has not yet been picked up by Colony. | — | — |
new | colony:new | active | Colony has detected this issue and will start analyzing it shortly. | ready-for-dev, needs-clarification, human-review-ready, done, waiting-for-subtasks, planning, dependency-blocked, parent-branch-pending, failure-blocked, analyzing, changes-requested, in-review, merge-pending | — |
planning | colony:planning | active | Colony is creating a step-by-step plan before writing any code. | ready-for-dev, new, waiting-for-subtasks, needs-clarification, done, in-review, human-review-ready, failure-blocked, analyzing, dependency-blocked, changes-requested, merge-pending | — |
analyzing | colony:analyzing | active | Colony is reading the codebase to understand scope and context. | ready-for-dev, needs-clarification, human-review-ready, done, waiting-for-subtasks, planning, dependency-blocked, parent-branch-pending, failure-blocked, new, changes-requested, in-review, merge-pending | — |
needs-clarification | colony:needs-clarification | awaiting-human | Colony cannot proceed without more information — check the issue for a question. | analyzing, new, planning, ready-for-dev, dependency-blocked, failure-blocked, changes-requested, in-review, merge-pending, human-review-ready, waiting-for-subtasks, done | — |
ready-for-dev | colony:ready-for-dev | active | Planning is complete; Colony is queued to start writing code. | in-review, done, merge-pending, waiting-for-subtasks, analyzing, planning, human-review-ready, dependency-blocked, failure-blocked, new, changes-requested | — |
dependency-blocked | — | blocked | This issue is waiting on another issue or task to finish first. | — | auto → analyzing |
parent-branch-pending | colony:parent-branch-pending | blocked | Colony is waiting for the parent epic to get its own branch before this sub-epic can proceed. | — | auto → analyzing |
failure-blocked | colony:failure-blocked | blocked | This issue hit a failure or exhausted retries — an operator must retry or cancel. | in-review, human-review-ready, analyzing, changes-requested, planning, needs-clarification | manual → analyzing |
changes-requested | colony:changes-requested | active | A reviewer requested changes — Colony is addressing the feedback. | in-review, done, merge-pending, waiting-for-subtasks, analyzing, planning, human-review-ready, dependency-blocked, failure-blocked, new | — |
in-review | colony:in-review | active | A pull request is open and under review. | merge-pending, changes-requested, human-review-ready, waiting-for-subtasks, ready-for-dev, done, failure-blocked, dependency-blocked | — |
merge-pending | colony:merge-pending | active | Review passed — Colony will merge automatically once CI completes. | done, analyzing, human-review-ready, in-review, failure-blocked, changes-requested, ready-for-dev, dependency-blocked, waiting-for-subtasks | — |
human-review-ready | colony:human-review-ready | awaiting-human | A PR is open and waiting for your approval before Colony can merge. | analyzing, changes-requested, ready-for-dev, in-review, merge-pending, dependency-blocked, failure-blocked, waiting-for-subtasks, done | — |
waiting-for-subtasks | colony:waiting-for-subtasks | active | This issue is split into subtasks; Colony is waiting for all subtasks to complete. | done, in-review, failure-blocked, merge-pending, human-review-ready | — |
done | colony:done | terminal | This issue is complete and its PR has been merged or closed. | — | — |
paused | colony:paused | awaiting-human | An operator paused this issue; work will resume when you click Resume. | — | — |
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
Section titled “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). A pure projection of Postgres — editing it by hand has no effect; unblock with /colony:retry or colony unblock <n>. |
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. |
colony:dependabot | composeFlagLabel(prefix, 'dependabot') | Applied at intake to every Dependabot tracking issue (pinned to the colony-dependabot workflow). Use it to filter these issues out of GitHub searches: is:issue is:open -label:colony:dependabot. See colony-dependabot workflow. |
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(). Tracks created by strategy apply use a second namespace, <prefix>:strategy-<name> (e.g. colony:strategy-api-latency), built with composeFlagLabel. Both are recognised by isSiTrackLabel, so the developer and planner treat issues carrying either as SI issues. The concrete set of
tracks — and their label suffixes — is set per track in the Postgres-backed track store (dashboard
Tracks tab or POST /api/tracks), so this namespace is provisioned alongside the flag labels above rather than being a fixed list.
Operator Command Labels
Section titled “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:enqueueExample — pause an in-flight issue, then resume it later:
gh issue edit 123 --add-label colony:pausedgh issue edit 123 --remove-label colony:pausedExample — opt an issue out of automatic intake:
gh issue edit 123 --add-label colony:ignorePriority Label
Section titled “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
Section titled “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.