Skip to content

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 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.


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.

StateLabelTypeDescriptionTransitions toRecovery
unlabeled—awaiting-humanThis issue has not yet been picked up by Colony.——
newcolony:newactiveColony 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—
planningcolony:planningactiveColony 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—
analyzingcolony:analyzingactiveColony 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-clarificationcolony:needs-clarificationawaiting-humanColony 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-devcolony:ready-for-devactivePlanning 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—blockedThis issue is waiting on another issue or task to finish first.—auto → analyzing
parent-branch-pendingcolony:parent-branch-pendingblockedColony is waiting for the parent epic to get its own branch before this sub-epic can proceed.—auto → analyzing
failure-blockedcolony:failure-blockedblockedThis issue hit a failure or exhausted retries — an operator must retry or cancel.in-review, human-review-ready, analyzing, changes-requested, planning, needs-clarificationmanual → analyzing
changes-requestedcolony:changes-requestedactiveA 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-reviewcolony:in-reviewactiveA 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-pendingcolony:merge-pendingactiveReview 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-readycolony:human-review-readyawaiting-humanA 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-subtaskscolony:waiting-for-subtasksactiveThis issue is split into subtasks; Colony is waiting for all subtasks to complete.done, in-review, failure-blocked, merge-pending, human-review-ready—
donecolony:doneterminalThis issue is complete and its PR has been merged or closed.——
pausedcolony:pausedawaiting-humanAn 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 are independent of the state machine — they mark a condition alongside whatever state label is currently set, rather than replacing it.

LabelConstantMeaning
colony:blockedBLOCKED_LABELIssue 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:pausedPAUSED_LABELIssue processing is suspended. Also an operator-settable command label — see below.
colony:activeACTIVE_LABELIssue currently has an in-flight worker task.
colony:epicEPIC_LABELIssue has been decomposed into sub-issues via /colony:decompose or planning.
colony:needs-humanNEEDS_HUMAN_LABELEscalation marker — the reviewer, merger, analyzer, or the worker’s budget enforcement determined the issue needs direct human attention.
colony:needs-inputNEEDS_INPUT_LABELColony needs additional information from a human before it can proceed.
colony:no-work-neededNO_WORK_NEEDED_LABELAn agent determined the issue requires no code change.
colony:staleSTALE_LABELIssue has been idle past the configured staleness threshold.
colony:ignoreIGNORE_LABELOpts an issue out of automatic intake. Also an operator-settable command label — see below.
colony:self-improvementSELF_IMPROVEMENT_LABELIssue was generated by Colony’s self-improvement loop rather than a human reporter.
colony:alertalertLabel()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:digestdigestLabel()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-probedoctorProbeLabel()Created and immediately deleted by colony doctor’s write-access probe; transient, never left on an issue or PR.
colony:dependabotcomposeFlagLabel(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.


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.

LabelConstantEffect
colony:enqueueENQUEUE_LABELSeeds a new, untracked issue into the Colony pipeline — the same effect as commenting /colony:enqueue.
colony:pausedPAUSED_LABELToggles pause/resume for an in-flight issue — the same effect as /colony:pause and /colony:resume.
colony:ignoreIGNORE_LABELOpts 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:

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

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

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

Example — opt an issue out of automatic intake:

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

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.


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.