Skip to content

Author and Register a Custom Workflow

A workflow definition controls states, executors, outcome routes, recovery traits, operator actions, triggers, and terminal hooks. Every issue is pinned to a workflow ID and version when it enters the pipeline, so a later definition cannot silently change an in-flight issue.

The safest custom workflow is a deliberate edit of a valid built-in definition. A small-looking example is often invalid because each executor has several possible outcomes and every executor-bearing path needs a reachable blocked fallback.

For self-hosted Colony, export the current default:

Terminal window
colony workflow show --builtin colony-default > .colony/workflow.yaml

Change workflow.id, workflow.name, and workflow.version before editing behavior. Keep the original file in version control so reviews show exactly which routes changed.

In Colony Cloud, Standards → Workflows (/standards/workflows) offers New version, Clone and Edit as new version to people with the Standards grant. Starting from an existing registered version provides the same safer baseline.

schema_version: 1
workflow:
id: my-workflow
version: 1
name: "My workflow"
intake:
initial_state: new
trigger_label: colony:enqueue
states:
new:
type: active
executor: builtin:analyze
on:
success: ready-for-dev
needs_clarification: needs-clarification
no_work_pr_open: ready-for-dev
no_work_done: done
decompose: failure-blocked
escalate_to_planning: failure-blocked
dependency_blocked: failure-blocked
parent_branch_pending: failure-blocked
failure: failure-blocked
error: failure-blocked
transitions: [ready-for-dev, needs-clarification, failure-blocked, done]
ready-for-dev:
type: awaiting-human
on: {}
transitions: [done, failure-blocked]
needs-clarification:
type: awaiting-human
on:
clarification_received: new
transitions: [new]
failure-blocked:
type: blocked
recovery: manual
on: {}
transitions: [new]
done:
type: terminal
operator_actions:
retry:
description: "Retry the current executable state."
framework: true
reopen:
description: "Return completed work to intake."
intent: reopen
from: [done]
to: new

This is a schema illustration, not a drop-in replacement for colony-default: it intentionally stops at a human-controlled ready-for-dev state. Preserve every route needed by an executor you retain.

Executor references use builtin:<name> or plugin:<package>/<key>. Current built-in names include underscores where shown by the built-in file—for example, builtin:ci_repair.

Terminal window
colony workflow validate .colony/workflow.yaml

The command exits 0 and prints the workflow ID, version, state count, action count, and content hash when valid. Parse/schema failures exit 2.

Validation checks include:

  • the intake, route, transition, action, and trigger targets exist;
  • terminal states have no executor, routes, or transitions;
  • blocked states declare recovery;
  • hooks appear only on terminal states;
  • cross-state on targets are also declared transitions;
  • executor-bearing paths have a reachable blocked fallback;
  • executor and trigger references use a valid format;
  • reserved outcomes are not used as ordinary route keys.

Validation cannot prove that a plugin’s runtime behavior matches its declared outcomes or that every external side effect will succeed. Test new definitions with disposable issues.

  1. Open Standards → Workflows (/standards/workflows).
  2. Use Edit as new version or Clone to change an existing workflow, New version to start from a blank or stored draft, or Import YAML to load a file as the draft.
  3. Edit the draft on the Map and in Tuning, clear any errors in the fault list, and click Publish. Published versions are immutable.
  4. Click Activate… on the published version and choose the repositories.

Activation sets the repository’s default workflow. New issues pin it, and issues already in flight keep the version they started with. The repository’s Workflow page also lets you set the default and add routed workflows; selecting an entry in its Workflow registry list only changes what the page displays. Verify the pinned workflow on a newly ingested issue.

  1. Validate the YAML and review its diff against the source workflow.
  2. Test intake, one happy path, each changed recovery route, and relevant operator actions in a non-production repository.
  3. Activate it for one repository in Cloud, or supply it to one repository in self-hosted Colony, and test only newly ingested issues.
  4. Observe task creation and state transitions, not just GitHub labels.
  5. Keep the prior version registered so pinned issues and audit history remain resolvable.