Publishing processes
Every save is a draft. Its author submits it for review, an owner or admin publishes it after reading the diff — with separation of duties on, one who did not write it — and runs start only from the published version. Rollback publishes an earlier version again.
A change to a process changes what the autopilot does with real cases. So a saved version does not run by itself: its author submits it, and an owner or admin publishes it. With the company's separation of duties on — the default — those are two different people.
| State | What it means | Runs from it |
|---|---|---|
draft | Saved from the canvas, imported (JSON / BPMN) or drafted from text. | Only its author's shadow test run. |
in_review | Its author submitted it and asked for review. | Only its author's shadow test run. |
published | An owner or admin published it (with separation of duties on, not its author). At most one per process. | Every new run — manual, API key, trigger. |
retired | It was published before; a newer one replaced it. | None, until it is rolled back to. |
Runs already started keep their version
A run is pinned to the graph it started with (graph_version, graph_hash) for its whole
life. Publishing or rolling back changes only what new runs start from; a run waiting
for a signature resumes on the version it started on.
The rule: an owner or admin publishes — and with separation of duties, not the author
-
Submit — only the version's author submits it, and only if it is runnable (no governance violations; otherwise
422with the violations). -
Publish — an owner or admin. A manager is refused with
403whatever they wrote. A machine (API key, trigger) can read versions but never submits or publishes. Whether the author may publish their own version follows the company's separation of duties switch — the same one that stops a person signing two gates of one run:Separation of duties Who publishes a version on (default) An owner or admin who did not author it. The author is refused with 403, even as the owner.off Any owner or admin, its author included. An owner or admin turns it off with
PUT /governance/policyand{"separation_of_duties": false}(or on the Settings page); the change is in the audit chain. -
Return to draft — the author withdraws their own version, or an owner or admin sends it back; sending someone else's version back needs a reason.
Every move is one transaction with its entry in the audit chain:
process_submitted, process_returned, process_published, process_rolled_back. Each
records who made the move and in which role, the version and its executable hash, its
author, the note, and the published version before and after (published_before,
published_after). A publish or rollback entry also records sod — the rule it was
published under — and by_author: "sod": false, "by_author": true is a version its own
author published. If the entry cannot be written, nothing moves (503).
Working alone
In a company with one owner and nobody else, separation of duties leaves nobody who may publish what you write. Either invite a second owner or admin under Team (see Set up your team), or turn separation of duties off: then you go from import to a real run on your own — import, submit, publish, run — and every version you publish says so in the audit chain and in the admin ("Published by its author — separation of duties is off for this company"). Turning it off also lets one person sign two gates of the same run.
In the admin
Open Processes and pick a process. The list shows the latest version and its state,
and which version runs (v4 in review · runs v3). Under the canvas, Versions lists
every version with its state and author. Select one:
- a draft shows Submit for review and Test run in shadow;
- a version in review shows Publish and Return to draft, and the diff;
- a retired version shows Roll back to this version, and the diff.
A button you may not use is disabled, with the reason under it — your role, separation of duties, or the state. The diff says what publishing that version would change against the published one. If the diff could not be read it says Diff not read, and Publish waits until it is: a diff that did not load is never shown as "no changes".
From the API
List the versions, with what you may do with each:
curl -s "$API/process-templates/drafts/refund-approval/versions" \
-H "Authorization: Bearer $TOKEN" \
| jq '{published_version, versions: [.versions[] | {version, state, created_by, publish: .actions.publish}]}'actions.<submit|return|publish|rollback|shadow_run> is {allowed, reason} for the caller —
the same rule the moves enforce.
The author submits version 4:
curl -s -X POST "$API/process-templates/drafts/refund-approval/versions/4/submit" \
-H "Authorization: Bearer $AUTHOR_TOKEN" \
-H "Content-Type: application/json" \
-d '{"note": "Adds the fraud-desk gate before the refund."}'The publisher reads the diff against the published version:
curl -s "$API/process-templates/drafts/refund-approval/diff?version=4" \
-H "Authorization: Bearer $ADMIN_TOKEN" \
| jq '{against, identical, changes, steps, edges, gate_forms, sla, connectors}'| Section | What it lists |
|---|---|
steps | Steps added, removed, and changed with each changed field (before → after). |
edges | Connections added and removed (with their branch label). |
gate_forms | Per gate: its form added, removed or changed. |
sla | Per step: its deadline (sla_spec) or SLA prose added, removed or changed. |
connectors | Per step: the tool ids it calls, added, removed or changed. |
against is the version compared against (null when nothing is published yet — then
everything is new). Layout is not a change. identical: true means both versions pin the
same executable hash. Pass &against=<n> to compare with another version.
Then publishes it, naming the version the diff was read against:
curl -s -X POST "$API/process-templates/drafts/refund-approval/versions/4/publish" \
-H "Authorization: Bearer $ADMIN_TOKEN" \
-H "Content-Type: application/json" \
-d '{"against": 3}' | jq '{version, state, published_before, published_after}'If another version was published in the meantime, against no longer matches and the
publish is refused with 409 — read the diff again. Version 3 is now retired.
| Answer | When |
|---|---|
403 | A machine; a role other than owner or admin; the version's own author. |
404 | No such process or version in your company. |
409 | The version is not in the state the move needs, or against is stale. |
422 | The version is not runnable; a rollback or a return of someone else's version without a reason. |
503 | The audit entry could not be written; nothing moved. |
Roll back
Rollback publishes a retired version again, under the same rule as publishing (an owner or admin; with separation of duties on, one who did not author that version) and with a reason:
curl -s -X POST "$API/process-templates/drafts/refund-approval/versions/3/rollback" \
-H "Authorization: Bearer $ADMIN_TOKEN" \
-H "Content-Type: application/json" \
-d '{"note": "v4 sends every refund to the fraud desk; back to v3 while we fix it.", "against": 4}'Version 3 is published again and version 4 retired; the process_rolled_back entry names
both.
Runs start from the published version
curl -s -X POST "$API/process-runs" \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{"vertical": "refund-approval", "draft": true, "inputs": {"order_id": "O-1001"}}' \
| jq '{status, graph_version, graph_hash}'Without draft_version the run starts from the published version; if nothing is published
the answer is 409. Naming a draft_version that is not published is refused with 409
too — unless it is the author's shadow test run.
Test a draft in shadow
Before a version is published, its author can run it with "shadow": true. Every
connector of that run is shadowed, on start and on every resume — the run records what
each tool would have done and nothing leaves Minctrl. It parks and is signed like any run,
and its run_started and gate_signed entries in the audit chain say "shadow": true.
curl -s -X POST "$API/process-runs" \
-H "Authorization: Bearer $AUTHOR_TOKEN" \
-H "Content-Type: application/json" \
-d '{"vertical": "refund-approval", "draft": true, "draft_version": 4, "shadow": true,
"inputs": {"order_id": "O-1001"}}' | jq '{status, shadow, graph_version}'Anyone else asking for a shadow run of an unpublished version gets 403.
A shadow test run is its author's private test: when it parks, only its author is notified (not the people who sign real runs), and its Slack message carries Open in Minctrl only — a shadow run is never signed from Slack. Signed in Minctrl, it stays shadowed on every resume.
Processes saved before publishing existed
When publishing arrived, the latest version of every process became published and every
older one retired, so what ran before kept running. They show published by migration.
To change one now, save a new version and take it through review.
Configure gates and autonomy
How the resolver routes a step by risk tier — low auto-clears, medium goes to a judge panel, irreversible always parks for a human — and how reversibility and blast radius decide the tier.
Promoting between environments
Move a published process from one Minctrl installation to another as a signed release bundle — Ed25519 signatures, trusted installations, import into review, connector mapping, the promotion log and a drift check.