Worker Versioning
Worker Versioning is a Temporal feature that allows you to confidently deploy new changes to the Workflows running on your Workers without breaking them. Temporal enables this by helping you manage different builds or versions, formally called Worker Deployment Versions.
For most teams, Worker Versioning should be the default recommendation for deploying Workflow code changes in production. If you can run versioned worker deployments, prefer Worker Versioning over patching.
Worker Versioning unlocks important benefits for users of blue-green or rainbow deployments.
- Ramping traffic gradually to a new Worker Deployment Version.
- Verifying a new Deployment Version with tests before sending production traffic to it.
- Instant rollback when you detect that a new Deployment Version is broken.
- Improved error rates when adopting it.
In addition, Worker Versioning introduces Workflow Pinning. For pinned Workflow Types, each execution runs entirely on the Worker Deployment Version where it started. You need not worry about making breaking code changes to running, pinned Workflows.
To use Workflow Pinning, we recommend using rainbow deployments.
Watch this Temporal Replay 2025 talk to learn more about Worker Versioning and see a demo.
Minimum versions
Self-hosted users:
- Minimum Temporal CLI version v1.4.1
- Minimum Temporal Server version: v1.29.1
- Minimum Temporal UI version v2.38.0
Getting Started with Worker Versioning
To get started with Worker Versioning, you should understand some concepts around versioning and deployments.
- A Worker Deployment is a deployment or service across multiple versions. In a rainbow deployment, more than two active Deployment Versions can run at once.
- A Worker Deployment Version is a version of a deployment or service. It can have multiple Workers polling on multiple Task Queues, but they all run the same build.
- A Build ID, in combination with a Worker Deployment name, identifies a single Worker Deployment Version.
- When a versioned worker polls on a task queue, that task queue becomes part of that Worker's version. That version's Worker Deployment controls how the task queue matches Workflow Tasks with Workers.
- Using Workflow Pinning, you can declare each Workflow type to have a Versioning Behavior, either Pinned or
Auto-Upgrade.
- A Pinned Workflow is guaranteed to complete on a single Worker Deployment Version.
- An Auto-Upgrade Workflow will automatically move to a new code version as you roll it out, specifically its Target Worker Deployment Version (defined below). Therefore, Auto-Upgrade Workflows are not restricted to a single Deployment Version and need to be kept replay-safe manually, i.e. with patching.
- Both Pinned and Auto-Upgrade Workflows are guaranteed to start only on the Current or Ramping Version of their Worker Deployment.
- Pinned Workflows are designed for use with rainbow deployments. See Deployment Systems.
- Pinned Workflows don't need to be patched, as they run on the same worker and build until they complete.
- If you expect your Workflow to run longer than you want your Worker Deployment Versions to exist, you should mark your Workflow Type as Auto-Upgrade.
- Each Worker Deployment has a single Current Version which is where Workflows are routed to unless they were previously pinned on a different version.
- Each Worker Deployment can have a Ramping Version which is where a configurable percentage of Workflows are routed to unless they were previously pinned on a different version.
- For a given Workflow, its Target Worker Deployment Version is the version it will move to next.
Setting up your deployment system
If you haven't already, you'll want to pick a container deployment solution for your Workers.
You also need to pick among three common deployment strategies:
- A rolling deployment strategy upgrades Workers in place with little control over how quickly they cut over and only a slow ability to roll Workers back. Rolling deploys have minimal footprint but tend to provide lower availability than the other strategies and are incompatible with Worker Versioning.
- A blue-green deployment strategy maintains two "colors," or Worker Deployment Versions simultaneously and can control how traffic is routed between them. This allows you to maximize your uptime with features like instant rollback and ramping. Worker Versioning enables the routing control that blue-green deployments need.
- A rainbow deployment strategy is like blue-green but with more colors, allowing Workflow Pinning. You can deploy new revisions of your Workflows freely while older versions drain. Using Worker Versioning, Temporal lets you know when all the Workflows of a given version are drained so that you can sunset it.
You also have the option to use the Temporal Worker Controller to automatically enable rainbow deployments of your Workers if you're using Kubernetes.
If you cannot yet support blue-green or rainbow style deployments, use patching as a fallback while you work toward a versioned deployment model.
Choosing a Versioning Behavior
The right versioning behavior depends on how long your Workflows run relative to your deployment frequency.
Decision guide
| Workflow Duration | Uses Continue-as-New? | Recommended Behavior | Patching Required? |
|---|---|---|---|
| Short (completes before next deploy) | N/A | PINNED | Never |
| Medium (spans multiple deploys) | No | AUTO_UPGRADE | Yes |
| Long (weeks to years) | Yes | PINNED + upgrade on CaN | Never |
| Long (weeks to years) | No | AUTO_UPGRADE + patching | Yes |
Examples by Workflow type
| Workflow Type | Duration | Recommended Behavior | Notes |
|---|---|---|---|
| Order processing | Minutes | PINNED | Completes before next deploy |
| Payment retry | Hours | PINNED or AUTO_UPGRADE | Depends on deploy frequency |
| Subscription billing | Days | AUTO_UPGRADE | May span multiple deploys |
| Customer entity | Months-Years | PINNED + upgrade on CaN | Uses Continue-as-New pattern |
| AI agent / Chatbot | Weeks | PINNED + upgrade on CaN | Long sleeps, uses CaN |
| Compliance audit | Months | AUTO_UPGRADE + patching | Cannot use CaN (needs full history) |
If your Workflow uses Continue-as-New to manage history size, you can upgrade to new Worker Deployment Versions at the CaN boundary without patching. See Upgrading on Continue-as-New.
Default Versioning Behavior Considerations
If you are using blue-green deployments, you should default to Auto-Upgrade and should not use Workflow Pinning.
Otherwise, if your Worker and Workflows are new, we suggest not providing a DefaultVersioningBehavior.
In general, each Workflow Type should be annotated as Auto-Upgrade or Pinned. If all of your Workflows will be short-running for the foreseeable future, you can default to Pinned.
Many users who are migrating to Worker Versioning will start by defaulting to Auto-Upgrade until they have had time to
annotate their Workflows. This default is the most similar to the legacy behavior. Once each Workflow Type is annotated,
you can remove the DefaultVersioningBehavior.
There is a possibility of a queue blocking limitation for new or Auto-Upgrade Workflows if there is a ramp, but one of the Current or Ramping versions is down or doesn't have enough capacity. This leads to other versions not getting Tasks or slowing down.
For example, you have a Current Version and a Ramping Version at 50%. If all of your Current Version Workers go down, you would expect at least 50% of new Workflows to go to the Ramping Version. This won't happen because the Tasks for the Current Version are blocking the queue.
Keep in mind that Child Workflows of a parent or previous Auto-Upgrade Workflow default to Auto-Upgrade behavior and not Unspecified.
You also want to make sure you understand how your Activities are going to work across different Worker Deployment Versions. Refer to the Worker Versioning Activity behavior docs for more details.
If you run Serverless Workers, each Worker Deployment Version's compute provider points at a specific Lambda function. In production, configure it with a qualified versioned ARN so Pinned Workflows remain truly pinned to the code they started against, regardless of whether your default behavior is Pinned or Auto-Upgrade. See Worker Versioning with Serverless Workers.