Configure Issue Intake and Workflow Routing

Intake answers two separate questions: should Colony ingest this issue? and which workflow should the ingested issue use? Configure them independently and test with new issues. Existing pipeline rows keep their pinned workflow ID and version.

Choose an intake mode

Mode	Behavior	Use it when
Tagged only	Colony ingests a new or eligible issue only after the provider carries the Colony enqueue marker.	You are onboarding, share the tracker with human-only work, or want explicit operator control.
All issues	Colony ingests every eligible newly discovered issue unless it carries an ignore marker.	The tracker is dedicated to Colony or your issue-creation process already guarantees compatible work.

Caution

Changing to all-issue intake can create an unbounded stream of work. Set cost ceilings, verify Worker capacity, and make sure ordinary team issues are safe to process before enabling it.

Colony Cloud

1. Open the repository in Colony Cloud and go to its settings.
2. Under intake, select Tagged only or All issues.
3. Save the repository configuration.
4. Return to the repository status or Pipeline view and confirm the configured mode before filing the test issue.

Self-Host

Set the default under the Mayor’s literal configuration key:

agents:
  sprint_master:
    intake_mode: tagged

Override one repository without changing the others:

repos:
  - owner: acme
    repo: payments
    intake_mode: all

repos[].intake_mode wins over agents.sprint_master.intake_mode. Because the repo-level field is startup configuration, restart or redeploy the Mayor after changing it. Run colony check --stage repository to confirm the resolved mode.

Enqueue or exclude one issue

With tagged intake, apply colony:enqueue or post /colony:enqueue on an eligible issue. On Azure DevOps, Colony projects flags as tags rather than creating a GitHub label object.

Use colony:ignore for work Colony must not ingest. Apply it before the next intake cycle; adding it after an issue has entered Postgres does not cancel the existing pipeline row. Use a workflow-valid cancel or pause action for already-ingested work.

Select the repository workflow

Prefer a built-in workflow until you can identify a state, transition, or gate it cannot express. In Colony Cloud, select an available workflow in the repository configuration. For self-hosted Colony, the runtime resolves a repository workflow in this order:

1. a Cloud-pushed marker when that source is available;
2. inline workflow YAML supplied by configuration;
3. .colony/workflow.yaml in the Worker checkout;
4. the built-in colony-default fallback.

Definitions are immutable once registered at a workflow ID and version. New intake pins the resolved pair; changing the repository default does not rewrite issues already in flight.

Caution

Colony Cloud can validate, register, and display custom definitions, but the current runtime does not treat every arbitrary registered definition as a selectable built-in. Do not point repository or intake routing at a custom ID until the runtime path that supplies that definition is documented and verified. See Author and Register a Custom Workflow.

Route different issues to different workflows

Self-hosted intake_rules are evaluated from top to bottom. The first matching rule wins; all predicates inside one rule must match, while labels matches any label in its list.

intake_rules:
  default: colony-default
  rules:
    - workflow: colony-content
      match:
        labels: [documentation]
        title_pattern: '^\[docs\]'

title_pattern and body_pattern are JavaScript-compatible regular expressions. Invalid expressions fail configuration validation. A rule that selects an unknown or unavailable workflow fails routing; Colony does not silently run a different workflow.

The intake_rules block hot-reloads. After editing it, use the monitor’s config-reload control or POST /api/config/reload, then inspect the reload outcome. This does not change pinned workflows on existing issues.

Test the policy

1. Keep intake in tagged mode and create a deliberately small issue without the enqueue marker. Confirm it does not appear in the pipeline.
2. Add the marker and confirm the issue is ingested once.
3. Inspect the issue detail, event history, or workflow snapshot and verify the pinned workflow ID and version.
4. Create one issue that matches a routing rule and one that falls through to the default.
5. Remove the test work or let it complete before expanding the policy.

Diagnose unexpected intake

Symptom	Check
Nothing enters	Repository enabled state, provider access, Mayor health, intake mode, enqueue/ignore markers, and webhook or polling activity.
Too many issues enter	Effective repo override, all-issue mode, and automation that creates issues without an ignore marker.
Wrong workflow is pinned	Rule ordering, predicate semantics, repository default, definition availability, and the issue’s labels/title/body at intake time.
A workflow change did not affect an active issue	Expected behavior: the issue keeps its pinned workflow version. Test with a new issue.

What next

• Configure Merge Policy and Branch Protection
• Writing for Colony
• Triage a Stuck Issue