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.
Start from a working definition
Section titled “Start from a working definition”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:
colony workflow show --builtin colony-default > .colony/workflow.yamlChange 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.
Definition structure
Section titled “Definition structure”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: newThis 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.
Validate locally
Section titled “Validate locally”colony workflow validate .colony/workflow.yamlThe 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
ontargets 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.
Register or supply the definition
Section titled “Register or supply the definition”- Open Standards → Workflows (
/standards/workflows). - 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.
- Edit the draft on the Map and in Tuning, clear any errors in the fault list, and click Publish. Published versions are immutable.
- 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.
Commit .colony/workflow.yaml to the target repository, or supply an inline workflow through the deployment configuration. The configuration override takes precedence over the repository file; otherwise Colony falls back to colony-default.
Colony validates and upserts the resolved definition when it processes the repository. Keep workflow.version immutable: create a higher version for every content change.
Roll out safely
Section titled “Roll out safely”- Validate the YAML and review its diff against the source workflow.
- Test intake, one happy path, each changed recovery route, and relevant operator actions in a non-production repository.
- Activate it for one repository in Cloud, or supply it to one repository in self-hosted Colony, and test only newly ingested issues.
- Observe task creation and state transitions, not just GitHub labels.
- Keep the prior version registered so pinned issues and audit history remain resolvable.