Worker Versioning

Deploy workflow code changes with zero downtime using build-id based versioning

Worker Versioning is in Pre-Release stage and not recommended for production use. Future breaking changes may be made if necessary. The Version Set concept and related APIs have been deprecated.

Overview

Worker Versioning simplifies deploying changes to Worker Programs by:

• Build ID routing - Route workflows to workers based on Build ID
• Determinism guarantee - Workflows started on a Build ID only run on that Build ID
• Zero-downtime deploys - Run multiple worker versions simultaneously
• Redirect rules - Control when to route new work to new versions
• Reachability API - Determine when old versions can be decommissioned

How It Works

Worker Versioning guarantees that workflow executions started on a particular Build ID will only be processed by workers of the same Build ID, unless instructed otherwise via Redirect Rules.

When to Use Worker Versioning

Best Suited For

Short-Running Workflows

Workflows that complete quickly, minimizing the time you need to run multiple worker versions simultaneously.

Blue-Green Deploys

Deployment strategy where each version runs at full capacity during rollout.

Alternatives for Long-Running Workflows

Run multiple versions long-term

If deployment frequency is low relative to workflow lifetime, you can afford running multiple versions for extended periods.

Break workflows into shorter segments

Use Continue-as-New with UseAssignmentRules versioning intent so each new execution starts on the latest Build ID.

return workflow.NewContinueAsNewError(ctx, workflowFunc, 
    workflow.WithVersioningIntent(temporal.VersioningIntentUseAssignmentRules))

Use patching for deterministic changes

Avoid nondeterministic changes by using Workflow Patching or GetCurrentBuildID() along with redirect rules.

Prerequisites

1. Server Version

   Temporal Server v1.24.0 or higher required for Worker Versioning API.

2. SDK Support

   Updating versioning rules:

   • Temporal CLI >= v0.13.1
   • Go SDK >= v1.27.0

   Creating versioned workers:

   • Go SDK >= v1.27.0
   • TypeScript SDK >= v1.11.0
   • Python SDK >= v1.7.0
   • Java SDK >= v1.25.0
   • .NET SDK >= v1.2.0

Build IDs

A Build ID is a free-form string identifying a worker version:

• Recommended format: Semantic version or git commit SHA
• Examples: v1.0.0, v2.1.3, abc123def456
• Assignment: Set when creating worker
• Persistence: Recorded with workflow execution metadata

// Example: Setting Build ID in Go SDK
workerOptions := worker.Options{
    BuildID: "v2.1.0",
    UseBuildIDForVersioning: true,
}
w := worker.New(client, taskQueue, workerOptions)

Assignment Rules

Assignment rules control which Build ID receives new workflow executions:

Default Assignment Rule

The rule with the highest precedence (most recent) is the default:

# Set default Build ID using CLI
temporal task-queue update-build-ids add-new-default \
  --task-queue my-task-queue \
  --build-id v2.0.0

New workflows are routed to the default Build ID unless overridden.

Compatible Versions

Mark Build IDs as compatible to enable gradual rollout:

# Mark v2.0.1 as compatible with v2.0.0
temporal task-queue update-build-ids add-new-compatible \
  --task-queue my-task-queue \
  --build-id v2.0.1 \
  --existing-compatible-build-id v2.0.0

Workflows started on v2.0.0 can now run on v2.0.1 workers.

Redirect Rules

Redirect rules force workflows from an old Build ID to a new one:

# Redirect all workflows from v1.0.0 to v2.0.0
temporal task-queue update-build-ids add-redirect-rule \
  --task-queue my-task-queue \
  --source-build-id v1.0.0 \
  --target-build-id v2.0.0

Use redirect rules carefully with long-running workflows. Redirecting to a version with nondeterministic changes will cause workflow task failures.

Deployment Workflow

1. Deploy new worker version

   Start workers with new Build ID running alongside existing version:

   # New worker pool
   ./worker --build-id v2.0.0 --task-queue my-queue
   
2. Add new Build ID as default

   Route new workflows to the new version:

   temporal task-queue update-build-ids add-new-default \
     --task-queue my-queue \
     --build-id v2.0.0
   
3. Monitor new version

   Verify new workflows execute successfully on v2.0.0.

   Check metrics:

   • Workflow success rate
   • Task failure rate
   • Error logs
4. Check reachability of old version

   Determine if old workers are still needed:

   temporal task-queue get-build-id-reachability \
     --task-queue my-queue \
     --build-id v1.0.0
   

   Wait until REACHABLE_BY_NEW_WORKFLOWS is false.

5. Decommission old workers

   Once old Build ID is no longer reachable, stop old workers:

   # Stop v1.0.0 workers
   kubectl scale deployment worker-v1 --replicas=0
   

Reachability API

The reachability API tells you if a Build ID can receive:

• New workflows - Default assignment rule targets this ID
• Existing workflows - Open workflows were started on this ID
• Open workflow tasks - Workflow tasks from open workflows

Reachability States

REACHABLE_BY_NEW_WORKFLOWS · bool

Build ID is the default and will receive new workflow starts

REACHABLE_BY_EXISTING_WORKFLOWS · bool

Build ID has open workflows that may generate tasks

REACHABLE_BY_OPEN_WORKFLOW_TASKS · bool

Build ID has pending workflow tasks to process

Example: Check Reachability

temporal task-queue get-build-id-reachability \
  --task-queue my-queue \
  --build-id v1.0.0 \
  --reachability-type existing-workflows

Task Queue Versioning Data

Versioning data is stored per task queue:

User Data Table

Versioning rules stored in task_queue_user_data table:

CREATE TABLE task_queue_user_data (
    namespace_id BINARY(16) NOT NULL,
    task_queue_name VARCHAR(255) NOT NULL,
    data MEDIUMBLOB NOT NULL,
    data_encoding VARCHAR(16) NOT NULL,
    version BIGINT NOT NULL,
    PRIMARY KEY (namespace_id, task_queue_name)
);

Versioned Task Matching

Matching Service routes tasks based on Build ID:

1. Worker polls with Build ID in PollWorkflowTaskQueue request
2. Task added to queue with associated Build ID from workflow metadata
3. Matching Service routes task to worker with matching Build ID
4. Assignment rules consulted for compatible Build IDs
5. Redirect rules applied if configured

See Matching Service for implementation details.

Best Practices

Use semantic versioning for Build IDs

Clear versioning makes debugging and rollback easier:

• v1.0.0, v1.0.1, v1.1.0 for releases
• Include git SHA for traceability: v1.0.0-abc123

Mark patch versions as compatible

Bug fixes that don’t change workflow logic:

temporal task-queue update-build-ids add-new-compatible \
  --build-id v1.0.1 \
  --existing-compatible-build-id v1.0.0

Blue-green deployment strategy

Run both versions at full capacity during rollout:

• Deploy v2 workers at 100% capacity
• Keep v1 workers at 100% capacity
• Switch default assignment to v2
• Monitor for issues
• Decommission v1 when safe

Monitor reachability before decommission

Always check reachability before stopping workers:

while true; do
  reachable=$(temporal task-queue get-build-id-reachability \
    --build-id v1.0.0 --reachability-type existing-workflows)
  if [ "$reachable" = "false" ]; then
    echo "Safe to decommission v1.0.0"
    break
  fi
  sleep 60
done

Migrating from Version Sets

Version Sets are deprecated. Migrate to Build ID-based versioning.

Migration process:

1. Stop using AddActivityTaskToVersionSet and AddWorkflowTaskToVersionSet
2. Set Build IDs on workers using UseBuildIDForVersioning
3. Convert Version Sets to Assignment Rules:
   # For each version in the set
   temporal task-queue update-build-ids add-new-compatible \
     --build-id $BUILD_ID \
     --existing-compatible-build-id $PREVIOUS_BUILD_ID
   
4. Update clients to use Build ID APIs
5. Remove Version Set configurations

See Also

Matching Service

Understand task routing with versioning

Workers

Learn about worker processes and polling

Task Queues

Understand task queue partitioning