Publish & Deploy

A workflow travels through three states before it actively routes agent work: draft, published, and deployed. Understanding each state prevents surprises when you edit a live workflow.

States at a glance

State	Meaning
`draft`	Canvas changes saved but not published. No trigger events route to this version.
`published`	A validated snapshot is live. New trigger events start instances on this version.
`deployed`	The published definition has been pushed to a connected Donmai runtime or written to the local filesystem. Required for self-hosted runners.
`archived`	The workflow has been retired. No new instances start; existing subscriptions stop routing.

Draft → publish

Every edit in the canvas goes to the draft. Publishing creates an immutable version snapshot and updates the live routing tip.

From the editor: Click Publish in the toolbar. The editor validates the canvas first - any errors must be resolved before the button becomes active.

Via API:

POST /api/workflows/{workflowId}/publish
Content-Type: application/json
Authorization: Bearer rsk_live_...

{
  "mode": "in-place",
  "changeReason": "Add Linear AgentSession close node"
}

The publish step runs the full validation pipeline. If validation fails, the API returns 422 with a ValidationResult issues array - no version is created.

The published version stays live while you edit the draft. Running instances are pinned to the version they started on - they are never disrupted by publishing a new version.

Before publish, the platform checks that all resources referenced by the workflow - agent definitions, LLM model profiles, credentials, capacity pools - exist and are connected. The Required Resources panel in the editor shows this check. A broken state (red banner) means at least one resource is missing and must be resolved before publish will succeed.

GET /api/workflows/{workflowId}/required-resources
Authorization: Bearer rsk_live_...

Returns a list of foundational node refs and whether each is resolvable.

Publish → deploy

For workflows that will run on a Donmai runtime (self-hosted or cloud), you must also deploy the definition after publishing.

Deploy endpoint:

POST /api/workflows/{workflowId}/deploy
Authorization: Bearer rsk_live_...

Behaviour depends on environment:

DONMAI_API_URL is set - the platform calls the Donmai network API and pushes the definition over the network.
DONMAI_API_URL is not set - the definition YAML is written to the local filesystem path configured for the runner.

Only the latest published version is deployed. If you have unpublished changes, publish first.

Clone a workflow

Use the Clone button in the workflow controls (or the API) to create a copy of the current workflow. The clone starts in draft state with all nodes and edges copied. Useful for creating variants of an SDLC template without modifying the original.

POST /api/workflows/{workflowId}/clone
Authorization: Bearer rsk_live_...

{ "name": "My SDLC (Fork)" }

Import from YAML / JSON

You can replace the canvas by importing a workflow definition:

POST /api/workflows/{workflowId}/import
Content-Type: application/json
Authorization: Bearer rsk_live_...

{
  "definition": "version: v2\nspec:\n  trigger: ...",
  "format": "yaml"   # or "json"
}

The import runs full validation before applying. If the definition is invalid the canvas is not modified. The import dialog in the editor accepts raw YAML or JSON.

If a saved workflow has a broken state flag (set when the canvas contains known-invalid structures that passed a previous, less-strict validation), a red banner appears at the top of the editor. The banner prevents publishing until the issues are resolved. Once resolved, clear the flag:

DELETE /api/workflows/{workflowId}/broken-state
Authorization: Bearer rsk_live_...

The broken-state flag is set automatically when the platform detects a definition that would fail current validation but was saved before stricter checks were introduced.

Status reference

The workflow list shows a status badge for each workflow:

Badge	Meaning
Draft	Has unsaved or unpublished changes
Published	Latest publish is live; no pending draft changes
Deployed	Published and pushed to a runner
Archived	Retired; no new instances
Broken	Broken-state flag is set; publish blocked

Archiving a workflow

Archived workflows stop routing trigger events. Existing running instances complete normally. Subscriptions backed by an archived workflow silently drop new trigger events - check the project_template_subscriptions vs trigger_subscriptions sync if you archive a workflow and notice events disappearing.

POST /api/workflows/{workflowId}/archive
Authorization: Bearer rsk_live_...

Archived workflows can be unarchived. The previous published version is restored as the live tip.

Versioning - immutable snapshots, diff, rollback
Validation - what runs before a version is created
Required Policies - operator-enforced workflow installs
Testing - test-run mode before going live