> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/temporalio/temporal/llms.txt
> Use this file to discover all available pages before exploring further.

# Worker Versioning

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

<Warning>
  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.
</Warning>

## 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.

```mermaid theme={null}
sequenceDiagram
    participant Client
    participant Matching
    participant WorkerV1
    participant WorkerV2
    
    Note over WorkerV1: Build ID: v1.0.0
    Note over WorkerV2: Build ID: v2.0.0
    
    WorkerV1->>Matching: Poll with Build ID v1.0.0
    WorkerV2->>Matching: Poll with Build ID v2.0.0
    
    Client->>Matching: Start workflow (uses default/latest)
    Matching->>WorkerV2: Route to v2.0.0 (latest)
    
    Note over Matching: Existing workflow on v1.0.0
    Matching->>WorkerV1: Route existing workflow tasks to v1.0.0
```

## When to Use Worker Versioning

### Best Suited For

<CardGroup cols={2}>
  <Card title="Short-Running Workflows" icon="clock">
    Workflows that complete quickly, minimizing the time you need to run multiple worker versions simultaneously.
  </Card>

  <Card title="Blue-Green Deploys" icon="arrows-left-right">
    Deployment strategy where each version runs at full capacity during rollout.
  </Card>
</CardGroup>

### Alternatives for Long-Running Workflows

<AccordionGroup>
  <Accordion title="Run multiple versions long-term">
    If deployment frequency is low relative to workflow lifetime, you can afford running multiple versions for extended periods.
  </Accordion>

  <Accordion title="Break workflows into shorter segments">
    Use Continue-as-New with `UseAssignmentRules` versioning intent so each new execution starts on the latest Build ID.

    ```go theme={null}
    return workflow.NewContinueAsNewError(ctx, workflowFunc, 
        workflow.WithVersioningIntent(temporal.VersioningIntentUseAssignmentRules))
    ```
  </Accordion>

  <Accordion title="Use patching for deterministic changes">
    Avoid nondeterministic changes by using [Workflow Patching](https://docs.temporal.io/workflows#patching) or `GetCurrentBuildID()` along with redirect rules.
  </Accordion>
</AccordionGroup>

## Prerequisites

<Steps>
  <Step title="Server Version">
    Temporal Server **v1.24.0** or higher required for Worker Versioning API.
  </Step>

  <Step title="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
  </Step>
</Steps>

## 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

```go theme={null}
// 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:

```bash theme={null}
# 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:

```bash theme={null}
# 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:

```bash theme={null}
# 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
```

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

## Deployment Workflow

<Steps>
  <Step title="Deploy new worker version">
    Start workers with new Build ID running alongside existing version:

    ```bash theme={null}
    # New worker pool
    ./worker --build-id v2.0.0 --task-queue my-queue
    ```
  </Step>

  <Step title="Add new Build ID as default">
    Route new workflows to the new version:

    ```bash theme={null}
    temporal task-queue update-build-ids add-new-default \
      --task-queue my-queue \
      --build-id v2.0.0
    ```
  </Step>

  <Step title="Monitor new version">
    Verify new workflows execute successfully on v2.0.0.

    Check metrics:

    * Workflow success rate
    * Task failure rate
    * Error logs
  </Step>

  <Step title="Check reachability of old version">
    Determine if old workers are still needed:

    ```bash theme={null}
    temporal task-queue get-build-id-reachability \
      --task-queue my-queue \
      --build-id v1.0.0
    ```

    Wait until `REACHABLE_BY_NEW_WORKFLOWS` is false.
  </Step>

  <Step title="Decommission old workers">
    Once old Build ID is no longer reachable, stop old workers:

    ```bash theme={null}
    # Stop v1.0.0 workers
    kubectl scale deployment worker-v1 --replicas=0
    ```
  </Step>
</Steps>

## 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

<ResponseField name="REACHABLE_BY_NEW_WORKFLOWS" type="bool">
  Build ID is the default and will receive new workflow starts
</ResponseField>

<ResponseField name="REACHABLE_BY_EXISTING_WORKFLOWS" type="bool">
  Build ID has open workflows that may generate tasks
</ResponseField>

<ResponseField name="REACHABLE_BY_OPEN_WORKFLOW_TASKS" type="bool">
  Build ID has pending workflow tasks to process
</ResponseField>

### Example: Check Reachability

```bash theme={null}
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:

```mermaid theme={null}
erDiagram
    TASK_QUEUE ||--o{ BUILD_ID_ASSIGNMENT : has
    TASK_QUEUE ||--o{ REDIRECT_RULE : has
    BUILD_ID_ASSIGNMENT ||--o{ BUILD_ID : references
    BUILD_ID ||--o{ COMPATIBLE_BUILD_ID : has
    
    TASK_QUEUE {
        string name
        string namespace
    }
    BUILD_ID_ASSIGNMENT {
        string build_id
        timestamp created_time
    }
    BUILD_ID {
        string id
        bool is_default
    }
    COMPATIBLE_BUILD_ID {
        string id
    }
    REDIRECT_RULE {
        string source_build_id
        string target_build_id
    }
```

### User Data Table

Versioning rules stored in `task_queue_user_data` table:

```sql theme={null}
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](/architecture/matching-service) for implementation details.

## Best Practices

<AccordionGroup>
  <Accordion title="Use semantic versioning for Build IDs" icon="tag">
    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`
  </Accordion>

  <Accordion title="Mark patch versions as compatible" icon="code-merge">
    Bug fixes that don't change workflow logic:

    ```bash theme={null}
    temporal task-queue update-build-ids add-new-compatible \
      --build-id v1.0.1 \
      --existing-compatible-build-id v1.0.0
    ```
  </Accordion>

  <Accordion title="Blue-green deployment strategy" icon="server">
    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
  </Accordion>

  <Accordion title="Monitor reachability before decommission" icon="chart-line">
    Always check reachability before stopping workers:

    ```bash theme={null}
    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
    ```
  </Accordion>
</AccordionGroup>

## Migrating from Version Sets

<Warning>
  Version Sets are deprecated. Migrate to Build ID-based versioning.
</Warning>

Migration process:

1. Stop using `AddActivityTaskToVersionSet` and `AddWorkflowTaskToVersionSet`
2. Set Build IDs on workers using `UseBuildIDForVersioning`
3. Convert Version Sets to Assignment Rules:
   ```bash theme={null}
   # 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

<CardGroup cols={2}>
  <Card title="Matching Service" href="/architecture/matching-service">
    Understand task routing with versioning
  </Card>

  <Card title="Workers" href="/concepts/workers">
    Learn about worker processes and polling
  </Card>

  <Card title="Task Queues" href="/concepts/task-queues">
    Understand task queue partitioning
  </Card>
</CardGroup>