Versions & Publishing

Workflows are version-controlled. Once a workflow has been published, the running system always executes a published version — an immutable snapshot of the steps, gates, trigger, and settings frozen at publish time. Editing happens in a draft that does not affect live executions until you publish it. This page covers the full lifecycle: draft, review, test, publish, and roll back.

How versioning works

• Drafts — Clicking Edit (new draft) on the workflow canvas starts a draft. All your changes (and any changes agents make on your behalf) land in the draft. New live executions keep running the currently active published version while the draft exists.
• Published versions — Publishing snapshots the draft into a new version: v1 on the first publish, then v2, v3, and so on. Published versions are immutable — they are never edited, only superseded.
• The active version — Exactly one published version is active at a time. New executions run the active version. Rolling back changes which version is active without creating a new one.
• Pinned executions — Every execution records the version it started on and keeps running it to completion, even if you publish or roll back while it is in flight.

Note

A workflow that has never been published runs directly from its saved configuration — versioning starts with the first publish. Workflows created through the create form or by agents are runnable straight away; publish when you want change control.

Reviewing and publishing a draft

The workflow canvas walks a draft through a short review flow before it can go live:

1. Edit the draft

   Open the workflow canvas and click Edit (new draft). Modify steps, gates, transitions, the trigger, or settings. The canvas header shows the current published version and the pending draft version (for example, “v3 · v4 pending”).

2. Approve each step

   Every step in the draft carries a review status. Steps start as drafts; approve each one as you review it. The Publish button stays disabled until every step is approved, so nothing goes live half-reviewed.

3. Fix validation issues

   The same validation that runs at save time runs against the draft — cycles, dangling transitions, missing approvers, fork/join mismatches, and decision gates with too few options all block publishing.

4. Test the draft

   Click Test to run a test execution against the draft snapshot. You compose a trigger payload (or accept a sample one) and the execution runs through the real engine — but as a test run, separate from production state. Test runs are linked from the canvas so you can inspect each step’s output before anything goes live.

5. Publish

   Click Publish. After you confirm, the draft becomes the next published version and the live executable graph for new executions. Publishing also enables the workflow if it was disabled.

Version history

The canvas has a version drawer listing every published version of the workflow: the version number, when it was published, who published it (a user or an agent), and the optional changelog note recorded at publish time. The currently active version is marked.

Rolling back

If a newly published version misbehaves, roll back from the version drawer: pick an earlier version and activate it. Rollback swaps which version is active — it does not delete anything, and it does not create a new version number.

• In-flight executions are unaffected. They finish on the version they started with.
• New executions run the rolled-back-to version from that point on.
• Version numbers keep counting up. If you were on v4 and roll back to v2, the next publish creates v5.

Tip

Rollback is the fast path when something is wrong in production. You can then fix the problem in a fresh draft at your own pace and publish it as the next version.

Versioning via agents and MCP

The same lifecycle is available to agents and external tools:

• publish_workflow_version — Promote the current draft to the next published version, with an optional changelog note.
• rollback_workflow_version — Activate a prior version.
• list_workflow_versions — List the version history for a workflow.
• update_workflow — Edits the draft. For a published workflow, follow it with publish_workflow_version to make the change live.

This means you can ask an agent in chat to “publish the dispatch workflow” or “roll back invoicing to the previous version” and it maps directly onto the same controls as the canvas.

Next steps

• Creating Workflows — Build a workflow from scratch.
• Workflow Execution — Monitor running executions and see how they pin to versions.
• Steps & Gates — Reference for all step types and gate configurations.