Temporal Worker Versioning

Worker Versioning

The BuildID/UseBuildIDForVersioning API is deprecated ¹. The current approach uses Worker Deployments (Public Preview, GA expected Q4 2025 ²). Minimum Go SDK version: v1.35.0+.

Core Concepts ³

• Worker Deployment: A service across multiple versions
• Worker Deployment Version: A specific version identified by Deployment Name + Build ID
• Pinned Workflows: Execute entirely on their original version; no patching needed
• Auto-Upgrade Workflows: Automatically move to newer versions; require patching for replay-safety

Version states: Inactive → Active → Draining → Drained

Worker Setup (Go SDK) ^{3 4}

buildID := os.Getenv("MY_BUILD_ID")
w := worker.New(c, "my-task-queue", worker.Options{
    DeploymentOptions: worker.DeploymentOptions{
        UseVersioning: true,
        Version: worker.WorkerDeploymentVersion{
            DeploymentName: "my-service",
            BuildId:        buildID,
        },
    },
})

Register Workflow as Pinned ^{3 4}

w.RegisterWorkflowWithOptions(MyWorkflow, workflow.RegisterOptions{
    VersioningBehavior: workflow.VersioningBehaviorPinned,
})

Starting a Workflow with Version Override ^{3 4}

opts := client.StartWorkflowOptions{
    ID:        "my-workflow-id",
    TaskQueue: "my-task-queue",
    VersioningOverride: &client.PinnedVersioningOverride{
        Version: worker.WorkerDeploymentVersion{
            DeploymentName: "my-service",
            BuildId:        "1.0",
        },
    },
}
we, err := c.ExecuteWorkflow(ctx, opts, MyWorkflow, input)

CLI Commands ³

# Check deployment versions
temporal worker deployment describe --name="my-service"
 
# Set current version (100% traffic)
temporal worker deployment set-current-version \
    --deployment-name "my-service" \
    --build-id "2.0"
 
# Ramp traffic to new version (gradual rollout)
temporal worker deployment set-ramping-version \
    --deployment-name "my-service" \
    --build-id "2.0" \
    --percentage=10
 
# Move a pinned workflow to a different version
temporal workflow update-options \
    --workflow-id "my-workflow-id" \
    --versioning-override-behavior pinned \
    --versioning-override-deployment-name "my-service" \
    --versioning-override-build-id "2.0"

Choosing a Strategy ³

Strategy	Use Case
Pinned	Rainbow deployments; workflows stay on original version until completion
Auto-Upgrade	Blue-green deployments; workflows move to new version (requires patching)

Footnotes

1. Worker Versioning (Legacy) | Temporal Docs - Deprecated BuildID API reference ↩

2. Replay 2025 Product Announcements | Temporal Blog - Latest feature announcements including Worker Versioning updates ↩

3. Worker Versioning | Temporal Docs - Official docs for the new Deployments-based versioning ↩ ↩² ↩³ ↩⁴ ↩⁵ ↩⁶

4. worker package | Go Packages - Go SDK worker package API reference ↩ ↩² ↩³