Guides

Workflow Versioning


A running workflow replays its journal. If you deploy new workflow code while executions are still in flight, those executions resume against code that did not write their history — the replay can diverge, silently.

Versioning closes that gap. A worker declares the code release it is running; the server records that release on an execution the first time the worker claims it, and from then on only workers declaring the same release are given that execution.

Declaring a release

The value is opaque — a git sha, an image digest, a release tag. The server compares it for equality and never parses or orders it.

It normally comes from your build rather than being typed by hand, so every SDK reads ORCHER_VERSION_ID from the environment:

1
ORCHER_VERSION_ID="$(git rev-parse --short HEAD)"

You can also set it explicitly, which takes precedence over the environment:

1
use orcher::prelude::*;
2
3
let worker = Worker::builder()
4
.server_url("http://localhost:50051")
5
.task_queue("orders")
6
.version_id("v1.4.2-abc123")
7
.build()
8
.await?;

An empty or whitespace-only value counts as not declared. This matters more than it looks: without it, an exported-but-empty ORCHER_VERSION_ID would pin executions to a release literally named "", which is indistinguishable from a real one and would look like versioning was working.

One execution · bound on first claim, never moved
1
Execution starts
bound_version_id is NULL · claimable by any worker
2
A worker on v1 claims it
server stamps bound_version_id = v1 — this is the only write that ever sets it
3
Workflow suspends · a v2 worker polls
refused · v2 ≠ v1 · the journal was not written by that code
4
A v1 worker polls
claimed · replay continues on the code it started on

What the server does

Binds on first claim, and never rebinds. The first worker to claim an execution stamps its release onto it. A later claim by a worker on a different release cannot move an in-flight execution onto new code — that rebinding is exactly the divergence this exists to prevent.

Routes claims by that binding. An execution bound to a release is only handed to a worker declaring the same release. An execution with no binding stays claimable by anyone.

A worker polls, declaring v2
is the execution bound?
Bound
= v2 → claimed
= v1 → refused, keeps waiting
Protects replay. Nothing overrides this — not even a queue policy.
Unbound
current release = v2 → claimed, binds to v2
current release = v1 → refused
no current release → claimed by anyone
Steers new work. This is the queue policy.

The trade-off worth understanding

A bound execution whose release has no running workers waits. It is not handed to a worker on a different release.

That is deliberate. The alternative — letting a mismatched worker take it once none match — trades a visible stall for a silent divergence:

no matching worker running
Wait (what Orcher does)the execution pauses; it resumes as soon as a worker on its release starts
Hand it over anywaythe execution replays against code its journal was not written by, with no signal

A stall is recoverable by an action always available to you: start a worker on that release. A divergence may not be recoverable at all.

Choosing where new work goes

Binding decides where an execution that has already started must run. It says nothing about a new execution — an unbound execution is claimable by any worker.

That matters during a rollout. With v1 and v2 workers both up, each new execution binds to whichever worker polls first, so new work keeps landing on the release you are trying to retire.

Give the queue a current release and new executions go there:

1
curl -X PUT http://localhost:8080/api/v1/task-queues/orders/current-release \
2
-H 'content-type: application/json' \
3
-d '{"versionId": "v1.4.2-abc123"}'
1
# what is it now?
2
curl http://localhost:8080/api/v1/task-queues/orders/current-release
3
# {"taskQueue":"orders","namespace":"default","currentVersionId":"v1.4.2-abc123"}

Sending null (or a blank string) clears the policy and returns the queue to "any release may take new work".

Rolling out a new release

  1. Deploy workers on the new release.
  2. Set the queue's current release to the new one. New executions now bind to it, and the old release starts draining.
  3. Keep the old-release workers running until the executions bound to them finish.
  4. Retire the old-release workers once nothing is waiting on that release.

Long-running workflows are the case to watch — an execution that sleeps for a week keeps its original release for that week, and retiring those workers early is what causes a stall.

Without step 2 the rollout still works, but the old release keeps picking up new work until you stop it, so it never finishes draining.

Rollout · v1 drains while v2 takes over
Before · only v1 deployed
v1 ████████ new + running
Step 1 · deploy v2 workers no policy yet
v1 █████ still taking new work
v2 ███ arbitrary split
New work lands on whichever polls first — v1 never finishes draining.
Step 2 · set current release to v2
v1 ███ draining only
v2 ██████ all new work
v1 now shrinks monotonically. Keep its workers running.
Step 3 · v1 drained → retire its workers
v2 ████████ new + running
GET /releases returns [] — nothing is bound to v1 any more.

Knowing when a release is safe to retire

1
curl http://localhost:8080/api/v1/task-queues/orders/releases
2
# {"taskQueue":"orders","namespace":"default",
3
# "releases":[{"versionId":"v1.3.9-def456","waiting":12}]}

Each entry is a release with executions still bound to it and not yet finished. An empty list means everything has drained and the old workers can go.

Run this during an incident too — a workflow that appears stuck is often one bound to a release with no workers left.

Unsticking an execution

If a release is already gone and executions are still bound to it, the first answer is to start a worker on that release. When that build no longer exists, move the execution instead:

1
curl -X POST http://localhost:8080/api/v1/executions/<executionId>/rebind \
2
-H 'content-type: application/json' \
3
-d '{"versionId": "v1.4.2-abc123"}'

Sending null unbinds it entirely, so any release may pick it up.

Not affected by versioning

Tasks. A release binds a workflow execution, because that is what replays a journal. Tasks are dispatched to any worker serving the queue.

Actors. Actor operations are not replayed from a workflow journal, so there is nothing to pin. Actor pollers deliberately do not carry a release.