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.
Versioning is opt-in and off by default. If no worker declares a release, nothing is recorded and claiming behaves exactly as it always has.
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:
1ORCHER_VERSION_ID="$(git rev-parse --short HEAD)"You can also set it explicitly, which takes precedence over the environment:
1use orcher::prelude::*;23let 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.
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.
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 anyway | the 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:
1curl -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?2curl http://localhost:8080/api/v1/task-queues/orders/current-release3# {"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".
This decides where new work goes, never where running work continues. An execution already bound to an older release keeps running on that release — that is the guarantee, and a queue policy does not override it.
Rolling out a new release
- Deploy workers on the new release.
- Set the queue's current release to the new one. New executions now bind to it, and the old release starts draining.
- Keep the old-release workers running until the executions bound to them finish.
- 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.
Knowing when a release is safe to retire
1curl http://localhost:8080/api/v1/task-queues/orders/releases2# {"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:
1curl -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.
Rebinding is deliberately a manual, considered action. Replay against different code is exactly what binding prevents, and Orcher cannot tell whether the new release is compatible with the journal the execution has already written — only you can. Executions that have already finished are refused.
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.