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.
Selecting a version
Section titled “Selecting a version”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:
| 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 an active version on load; if none is active, it selects the first version in the list.
Data source: GET /pipeline/workflow-definitions.
Per-version detail
Section titled “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
Section titled “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
Section titled “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
Section titled “Executors and plugins”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.
Operator actions
Section titled “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.
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>.
Admin controls
Section titled “Admin controls”Starting a draft
Section titled “Starting a draft”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.
Builtins
Section titled “Builtins”Builtin workflows are read-only. Clone is the only way to edit one, and the clone records the source it follows.
Fault list
Section titled “Fault list”The fault list stands beside the Map. Publish is disabled while the list holds an error.
Publish and discard
Section titled “Publish and discard”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
Section titled “Drafts”Drafts are kept automatically. There is one draft per tenant, and starting another asks before replacing it.
Import YAML
Section titled “Import YAML”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.
Grants
Section titled “Grants”| Action | Required grant |
|---|---|
| View workflow definitions and version history | Any member |
| View per-version state machine detail and YAML | Any 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 |
| 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. The list is paged (limit, offset, and a pagination object in the response); the dashboard loads every page. |
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 | Publish 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-drafts | Return the tenant’s current draft, if any. |
PUT | /pipeline/workflow-drafts | Keep the tenant’s draft. Requires the Standards grant workflow-definition-create. |
DELETE | /pipeline/workflow-drafts | Discard the tenant’s draft. Requires the Standards grant workflow-definition-create. |
GET | /pipeline/workflow-definitions/:workflowId/activation-preview | How many items are in flight across the chosen repositories. |
POST | /pipeline/workflow-definitions/:workflowId/activate | Activate a version. Body: { repos, version }. |