Workflows

The Workflows page shows all workflow definitions registered across your organization’s pipeline. A workflow definition is a state machine: a named set of states, the transitions between them, the executors that perform work in each state, and the operator actions that move issues between states manually.

Navigate to the page at /settings/workflows. This is the org-level view; for the per-repository workflow tab (which shows the active version and state machine for a specific repo), see Workflow. For a conceptual walkthrough of how one issue moves through the pipeline, see The Workflow.

Selecting a version

The left panel lists every registered workflow version, grouped by workflow ID. The workflow with the most recent active issue is badged Active.

Each entry shows:

Field	Description
Name	Human-readable name from the workflow definition (falls back to the workflow ID if omitted).
Version	Integer version number, displayed as v<N>. Higher numbers are newer registrations.
Source	Where the definition was loaded from (for example, a file path or cloud-push).
Age	Relative time since the version was registered (for example, “3 days ago”).

Click any entry to load its detail in the main panel. The dashboard auto-selects the active version on load; if no active version exists, it selects the highest-numbered version.

Data source: GET /pipeline/workflow-definitions.

Per-version detail

Selecting a version opens its detail in the main panel. The header shows the workflow name, version number, optional description, initial state, and trigger label (the GitHub label that routes new issues into this workflow, if the definition declares one).

State machine

A visual graph of the state machine renders beneath the header. Each node represents a state; arrows represent valid transitions. The graph reads left-to-right from the intake (initial) state.

States

Below the graph, a table lists every state in the workflow:

Column	Description
State	The state key used internally (for example, analyzing, in-review, done). Matches the state names in pipeline events and metrics.
Label	Human-readable display name shown in the dashboard (falls back to the state key if omitted).
Trait	The behavioral category of the state. One of: Active (work in progress), Blocked (cannot proceed without action), Awaiting human (waiting on a human step such as code review), or Terminal (final — no further transitions).
Executor	The executor that runs the work for this state, if any. States without executors show —.
Transitions	The states this state can transition to. — indicates a terminal state with no outbound transitions.

Executors and plugins

The Executors & Plugins section summarises every executor referenced in the workflow, grouped by type. Built-in executors (builtin:<name>) are provided by Colony’s core runtime; plugin executors (plugin:<package>/<key>) are provided by Colony plugins.

Operator actions

The Operator actions section lists every action an operator can trigger manually on issues in this workflow. Each entry shows the action name, the states it applies from, the state the issue moves to, and any side effects beyond the state transition.

YAML source

The definition’s raw YAML source is available in a collapsible YAML Source section at the bottom of the detail panel.

Data source: GET /pipeline/workflow-definitions/:workflowId?version=<N>.

Admin controls

Note

The controls below are visible only to owners and admins. Members see the same read-only version selector and detail panel, with no editing controls.

New version

The New version button (top-right, visible to owners and admins only) opens the workflow editor panel pre-populated with a skeleton YAML template. Edit the YAML, then submit to register a new version in the pipeline registry.

Edit as new version

Each version entry in the left panel includes an Edit as new version button (owners and admins only). Clicking it opens the editor panel pre-populated with the selected version’s YAML. Adjust the definition, increment the version: field, and submit to register the updated definition as a new version. If a version with the same workflow ID and version number already exists with different content, the API returns a conflict error — bump version: in the YAML to resolve it.

Registering a new version does not immediately change which version the pipeline uses for existing repos. Version selection per repo is managed in each repository’s workflow configuration.

Caution

Registration proves that Colony can parse and store the definition; it does not prove that the current runtime can select an arbitrary registered ID for new work. Existing issues retain their pinned workflow version, and the current Cloud runtime does not load arbitrary registered YAML through the repository selector as though it were a built-in. See Author and Register a Custom Workflow before rollout.

Role permissions

Action	Required role
View workflow definitions and version history	Any member
View per-version state machine detail and YAML	Any member
Register a new workflow version (POST /pipeline/workflow-definitions)	Owner or admin

APIs

Method	Path	Description
GET	/pipeline/workflow-definitions	List all registered workflow versions for the org, ordered by workflow ID and version (newest first). Returns a definitions array with one entry per version.
GET	/pipeline/workflow-definitions/:workflowId?version=N	Return the detail for a specific workflow version. Omit version to fetch the latest. Response includes the parsed snapshot (state machine) and raw yamlText.
POST	/pipeline/workflow-definitions	Register a new workflow version. Requires owner or admin role. Body: { yamlText: string }. Returns the registered workflowId, version, contentHash, and status (inserted or idempotent). A 409 is returned if the same version already exists with different content.