Skip to content

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.

Open Standards, then the Workflows tab (/standards/workflows). If a repository is in scope, choose Show tenant settings to reach this tenant-level view. This is the tenant-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.

The left panel lists every registered workflow version, grouped by workflow ID. A version is badged Active when an enabled repository’s workflow set uses it, so several can be Active at once. A published version that no repository uses reads “published and running nowhere”.

Each entry shows:

FieldDescription
NameHuman-readable name from the workflow definition (falls back to the workflow ID if omitted).
VersionInteger version number, displayed as v<N>. Higher numbers are newer registrations.
SourceWhere the definition was loaded from (for example, a file path or cloud-push).
AgeRelative 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 an active version on load; if none is active, it selects the first version in the list.

Data source: GET /pipeline/workflow-definitions.

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).

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.

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

ColumnDescription
StateThe state key used internally (for example, analyzing, in-review, done). Matches the state names in pipeline events and metrics.
LabelHuman-readable display name shown in the dashboard (falls back to the state key if omitted).
TraitThe 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).
ExecutorThe executor that runs the work for this state, if any. States without executors show —.
TransitionsThe states this state can transition to. — indicates a terminal state with no outbound transitions.

The Executors & Plugins section summarizes 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.

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.

The collapsible YAML section at the bottom of the detail panel is generated from the workflow. It does not keep comments or key order from a source file. Export YAML downloads the text as it is shown, as a file named for the workflow and version. Any member who can see the version can export it.

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

New version, Clone and Edit as new version each open a structured draft at /standards/workflows/draft. You author the workflow on the Map and in Tuning; no YAML is needed.

  • Map. Each lane has an Add station control. Each station opens in a station sheet, from its Map card or from its Tuning row.
  • Tuning. Cells edit in place. A blank cell means the setting is inherited.
  • Workflow settings. Covers the name, unit, proposal, intake, operator actions and triggers.

Builtin workflows are read-only. Clone is the only way to edit one, and the clone records the source it follows.

The fault list stands beside the Map. Publish is disabled while the list holds an error.

Publish v{N+1} publishes the draft as the next version of the workflow. It runs nothing until the version is activated. Discard draft returns to the last published version.

Publishing a new version does not change what any repository runs. To run a version, choose Activate… on it here, pick the repositories, and check how many items are in flight across them. You can also choose a repository’s workflow in its Standards → Settings. Existing issues keep their pinned workflow version. Built-in workflows have no Activate…; clone one first.

Drafts are kept automatically. There is one draft per tenant, and starting another asks before replacing it.

Import YAML takes a workflow file and makes it the tenant’s draft. The file is validated first. If it fails, a dialog lists each error as a path and a message, and nothing is changed. If it passes, the file opens as a structured draft. When a different draft is already stored, Import asks before replacing it. The draft is then edited on the Map and in Tuning, and comments and key order from the file are not kept. A file that carries a builtin’s workflow id becomes a draft, and Publish refuses it.

A stored draft that cannot be read as a workflow shows its problem with two controls: Download draft text and Discard draft. Download the text, fix it, and import it again.

Existing issues keep their pinned workflow version. See Author and Register a Custom Workflow before rollout.

ActionRequired grant
View workflow definitions and version historyAny member
View per-version state machine detail and YAMLAny member
Publish a new workflow version, keep or discard a draft (POST /pipeline/workflow-definitions, PUT / DELETE /pipeline/workflow-drafts)Standards grant workflow-definition-create
Activate a version on repositories (POST /pipeline/workflow-definitions/:workflowId/activate)Operations grant repo-settings-update
MethodPathDescription
GET/pipeline/workflow-definitionsList all registered workflow versions for the org, ordered by workflow ID and version (newest first). Returns a definitions array with one entry per version. The list is paged (limit, offset, and a pagination object in the response); the dashboard loads every page.
GET/pipeline/workflow-definitions/:workflowId?version=NReturn 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-definitionsPublish a new workflow version. Requires the Standards grant workflow-definition-create. 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.
GET/pipeline/workflow-draftsReturn the tenant’s current draft, if any.
PUT/pipeline/workflow-draftsKeep the tenant’s draft. Requires the Standards grant workflow-definition-create.
DELETE/pipeline/workflow-draftsDiscard the tenant’s draft. Requires the Standards grant workflow-definition-create.
GET/pipeline/workflow-definitions/:workflowId/activation-previewHow many items are in flight across the chosen repositories.
POST/pipeline/workflow-definitions/:workflowId/activateActivate a version. Body: { repos, version }.