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

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.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, Settings → Workflows offers New version and Edit as new version to owners and administrators. Starting from an existing registered version provides the same safer baseline.

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
      failure: failure-blocked
      error: failure-blocked
    transitions: [ready-for-dev, needs-clarification, failure-blocked]

  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.

Validate locally

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.

Open Settings → Workflows.
Use Edit as new version for a compatible change, or New version for a new workflow ID.
Increment workflow.version; registered definitions are immutable. Reusing the same ID/version with different content returns a conflict.
Register the YAML and inspect the rendered states and actions.

The repository’s Workflow page is a definition/version browser; selecting an entry there does not activate it. The repository Settings page also exposes a workflow-ID selector, but the currently deployed runtime does not yet load arbitrary Cloud-registered YAML through that selector. Treat Cloud registration as validation, version storage, and inspection—not as proof that new issues execute the definition. Verify the pinned workflow on a newly ingested issue; use a repository/config-supplied definition in self-hosted Colony when you need an executable custom workflow today.

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

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.
In self-hosted Colony, supply it to one repository and test only newly ingested issues. In Cloud, keep the version in the registry until runtime activation is supported and verified.
Observe task creation and state transitions, not just GitHub labels.
Keep the prior version registered so pinned issues and audit history remain resolvable.