From 39d3ef8d6881041621c9da559e2d8ad8db94238b Mon Sep 17 00:00:00 2001 From: Shivam Saraf Date: Wed, 17 Jun 2026 18:28:34 -0400 Subject: [PATCH 1/5] Add one-time versioning override API --- openapi/openapiv2.json | 14 +++++++++++++ openapi/openapiv3.yaml | 27 ++++++++++++++++++++++++++ temporal/api/workflow/v1/message.proto | 23 ++++++++++++++++++++++ 3 files changed, 64 insertions(+) diff --git a/openapi/openapiv2.json b/openapi/openapiv2.json index ea37162a0..dae1b3025 100644 --- a/openapi/openapiv2.json +++ b/openapi/openapiv2.json @@ -11097,6 +11097,16 @@ } } }, + "VersioningOverrideOneTimeMove": { + "type": "object", + "properties": { + "targetDeploymentVersion": { + "$ref": "#/definitions/v1WorkerDeploymentVersion", + "description": "Required. Worker Deployment Version to receive the one-time Workflow Task." + } + }, + "description": "Routes this workflow execution to a specific Worker Deployment Version for one\nsuccessful Workflow Task, then clears the override.\n\nThis does not force the workflow's normal Versioning Behavior to become\nPinned. After the Workflow Task completes on `target_deployment_version`,\nthe workflow execution's normal Versioning Behavior and Deployment Version\nare taken from the worker's completion response.\n\nFor example, if the target worker reports Pinned, the execution will remain\npinned after this override is cleared. If the target worker reports\nAutoUpgrade, the execution will resume AutoUpgrade routing after this\noverride is cleared.\n\nIf no Workflow Task completes on `target_deployment_version`, this override\nremains pending." + }, "VersioningOverridePinnedOverride": { "type": "object", "properties": { @@ -20147,6 +20157,10 @@ "type": "boolean", "description": "Override the workflow to have AutoUpgrade behavior." }, + "oneTime": { + "$ref": "#/definitions/VersioningOverrideOneTimeMove", + "description": "Move the workflow to a specific Worker Deployment Version for one successful Workflow Task." + }, "behavior": { "$ref": "#/definitions/v1VersioningBehavior", "description": "Required.\nDeprecated. Use `override`." diff --git a/openapi/openapiv3.yaml b/openapi/openapiv3.yaml index a2ec27cdd..9a1994d0a 100644 --- a/openapi/openapiv3.yaml +++ b/openapi/openapiv3.yaml @@ -18343,6 +18343,10 @@ components: autoUpgrade: type: boolean description: Override the workflow to have AutoUpgrade behavior. + oneTime: + allOf: + - $ref: '#/components/schemas/VersioningOverride_OneTimeMove' + description: Move the workflow to a specific Worker Deployment Version for one successful Workflow Task. behavior: enum: - VERSIONING_BEHAVIOR_UNSPECIFIED @@ -18377,6 +18381,29 @@ components: Pinned behavior overrides are automatically inherited by child workflows, workflow retries, continue-as-new workflows, and cron workflows. + VersioningOverride_OneTimeMove: + type: object + properties: + targetDeploymentVersion: + allOf: + - $ref: '#/components/schemas/WorkerDeploymentVersion' + description: Required. Worker Deployment Version to receive the one-time Workflow Task. + description: |- + Routes this workflow execution to a specific Worker Deployment Version for one + successful Workflow Task, then clears the override. + + This does not force the workflow's normal Versioning Behavior to become + Pinned. After the Workflow Task completes on `target_deployment_version`, + the workflow execution's normal Versioning Behavior and Deployment Version + are taken from the worker's completion response. + + For example, if the target worker reports Pinned, the execution will remain + pinned after this override is cleared. If the target worker reports + AutoUpgrade, the execution will resume AutoUpgrade routing after this + override is cleared. + + If no Workflow Task completes on `target_deployment_version`, this override + remains pending. VersioningOverride_PinnedOverride: type: object properties: diff --git a/temporal/api/workflow/v1/message.proto b/temporal/api/workflow/v1/message.proto index 4d35cb74b..811d5e70e 100644 --- a/temporal/api/workflow/v1/message.proto +++ b/temporal/api/workflow/v1/message.proto @@ -614,6 +614,9 @@ message VersioningOverride { // Override the workflow to have AutoUpgrade behavior. bool auto_upgrade = 4; + + // Move the workflow to a specific Worker Deployment Version for one successful Workflow Task. + OneTimeMove one_time = 5; } // Required. @@ -647,6 +650,26 @@ message VersioningOverride { temporal.api.deployment.v1.WorkerDeploymentVersion version = 2; } + // Routes this workflow execution to a specific Worker Deployment Version for one + // successful Workflow Task, then clears the override. + // + // This does not force the workflow's normal Versioning Behavior to become + // Pinned. After the Workflow Task completes on `target_deployment_version`, + // the workflow execution's normal Versioning Behavior and Deployment Version + // are taken from the worker's completion response. + // + // For example, if the target worker reports Pinned, the execution will remain + // pinned after this override is cleared. If the target worker reports + // AutoUpgrade, the execution will resume AutoUpgrade routing after this + // override is cleared. + // + // If no Workflow Task completes on `target_deployment_version`, this override + // remains pending. + message OneTimeMove { + // Required. Worker Deployment Version to receive the one-time Workflow Task. + temporal.api.deployment.v1.WorkerDeploymentVersion target_deployment_version = 1; + } + enum PinnedOverrideBehavior { // Unspecified. PINNED_OVERRIDE_BEHAVIOR_UNSPECIFIED = 0; From 4766bf7cdf8b4e394b532d7cc8bb58863743a05b Mon Sep 17 00:00:00 2001 From: Shivam Saraf Date: Wed, 17 Jun 2026 18:38:28 -0400 Subject: [PATCH 2/5] Rename one-time versioning override type --- openapi/openapiv2.json | 6 +++--- openapi/openapiv3.yaml | 8 +++++--- temporal/api/workflow/v1/message.proto | 7 ++++--- 3 files changed, 12 insertions(+), 9 deletions(-) diff --git a/openapi/openapiv2.json b/openapi/openapiv2.json index dae1b3025..18242adf7 100644 --- a/openapi/openapiv2.json +++ b/openapi/openapiv2.json @@ -11097,7 +11097,7 @@ } } }, - "VersioningOverrideOneTimeMove": { + "VersioningOverrideOneTimeOverride": { "type": "object", "properties": { "targetDeploymentVersion": { @@ -20158,8 +20158,8 @@ "description": "Override the workflow to have AutoUpgrade behavior." }, "oneTime": { - "$ref": "#/definitions/VersioningOverrideOneTimeMove", - "description": "Move the workflow to a specific Worker Deployment Version for one successful Workflow Task." + "$ref": "#/definitions/VersioningOverrideOneTimeOverride", + "description": "Temporarily override workflow task routing to a specific Worker Deployment Version\nuntil one Workflow Task completes there." }, "behavior": { "$ref": "#/definitions/v1VersioningBehavior", diff --git a/openapi/openapiv3.yaml b/openapi/openapiv3.yaml index 9a1994d0a..cd923a9b6 100644 --- a/openapi/openapiv3.yaml +++ b/openapi/openapiv3.yaml @@ -18345,8 +18345,10 @@ components: description: Override the workflow to have AutoUpgrade behavior. oneTime: allOf: - - $ref: '#/components/schemas/VersioningOverride_OneTimeMove' - description: Move the workflow to a specific Worker Deployment Version for one successful Workflow Task. + - $ref: '#/components/schemas/VersioningOverride_OneTimeOverride' + description: |- + Temporarily override workflow task routing to a specific Worker Deployment Version + until one Workflow Task completes there. behavior: enum: - VERSIONING_BEHAVIOR_UNSPECIFIED @@ -18381,7 +18383,7 @@ components: Pinned behavior overrides are automatically inherited by child workflows, workflow retries, continue-as-new workflows, and cron workflows. - VersioningOverride_OneTimeMove: + VersioningOverride_OneTimeOverride: type: object properties: targetDeploymentVersion: diff --git a/temporal/api/workflow/v1/message.proto b/temporal/api/workflow/v1/message.proto index 811d5e70e..d9e1a8cc6 100644 --- a/temporal/api/workflow/v1/message.proto +++ b/temporal/api/workflow/v1/message.proto @@ -615,8 +615,9 @@ message VersioningOverride { // Override the workflow to have AutoUpgrade behavior. bool auto_upgrade = 4; - // Move the workflow to a specific Worker Deployment Version for one successful Workflow Task. - OneTimeMove one_time = 5; + // Temporarily override workflow task routing to a specific Worker Deployment Version + // until one Workflow Task completes there. + OneTimeOverride one_time = 5; } // Required. @@ -665,7 +666,7 @@ message VersioningOverride { // // If no Workflow Task completes on `target_deployment_version`, this override // remains pending. - message OneTimeMove { + message OneTimeOverride { // Required. Worker Deployment Version to receive the one-time Workflow Task. temporal.api.deployment.v1.WorkerDeploymentVersion target_deployment_version = 1; } From f9ce6738b47b6c3bed259f9200005a9bafc5b369 Mon Sep 17 00:00:00 2001 From: Shivam Saraf Date: Wed, 17 Jun 2026 18:41:31 -0400 Subject: [PATCH 3/5] Clarify one-time override routing comment --- openapi/openapiv2.json | 2 +- openapi/openapiv3.yaml | 4 +++- temporal/api/workflow/v1/message.proto | 4 +++- 3 files changed, 7 insertions(+), 3 deletions(-) diff --git a/openapi/openapiv2.json b/openapi/openapiv2.json index 18242adf7..a9757f0c2 100644 --- a/openapi/openapiv2.json +++ b/openapi/openapiv2.json @@ -20159,7 +20159,7 @@ }, "oneTime": { "$ref": "#/definitions/VersioningOverrideOneTimeOverride", - "description": "Temporarily override workflow task routing to a specific Worker Deployment Version\nuntil one Workflow Task completes there." + "description": "Temporarily override workflow task routing to a specific Worker Deployment Version\nuntil one Workflow Task completes there. After completion, the workflow\nexecution's Versioning Behavior and Deployment Version come from the\nworker's completion response." }, "behavior": { "$ref": "#/definitions/v1VersioningBehavior", diff --git a/openapi/openapiv3.yaml b/openapi/openapiv3.yaml index cd923a9b6..641bc1997 100644 --- a/openapi/openapiv3.yaml +++ b/openapi/openapiv3.yaml @@ -18348,7 +18348,9 @@ components: - $ref: '#/components/schemas/VersioningOverride_OneTimeOverride' description: |- Temporarily override workflow task routing to a specific Worker Deployment Version - until one Workflow Task completes there. + until one Workflow Task completes there. After completion, the workflow + execution's Versioning Behavior and Deployment Version come from the + worker's completion response. behavior: enum: - VERSIONING_BEHAVIOR_UNSPECIFIED diff --git a/temporal/api/workflow/v1/message.proto b/temporal/api/workflow/v1/message.proto index d9e1a8cc6..e35f14723 100644 --- a/temporal/api/workflow/v1/message.proto +++ b/temporal/api/workflow/v1/message.proto @@ -616,7 +616,9 @@ message VersioningOverride { bool auto_upgrade = 4; // Temporarily override workflow task routing to a specific Worker Deployment Version - // until one Workflow Task completes there. + // until one Workflow Task completes there. After completion, the workflow + // execution's Versioning Behavior and Deployment Version come from the + // worker's completion response. OneTimeOverride one_time = 5; } From daa1442eb9111154796351628572641beb92ff9f Mon Sep 17 00:00:00 2001 From: Shivam Saraf Date: Wed, 17 Jun 2026 18:43:53 -0400 Subject: [PATCH 4/5] Clarify one-time override completion semantics --- openapi/openapiv2.json | 2 +- openapi/openapiv3.yaml | 4 ++-- temporal/api/workflow/v1/message.proto | 4 ++-- 3 files changed, 5 insertions(+), 5 deletions(-) diff --git a/openapi/openapiv2.json b/openapi/openapiv2.json index a9757f0c2..fbd65da2b 100644 --- a/openapi/openapiv2.json +++ b/openapi/openapiv2.json @@ -11105,7 +11105,7 @@ "description": "Required. Worker Deployment Version to receive the one-time Workflow Task." } }, - "description": "Routes this workflow execution to a specific Worker Deployment Version for one\nsuccessful Workflow Task, then clears the override.\n\nThis does not force the workflow's normal Versioning Behavior to become\nPinned. After the Workflow Task completes on `target_deployment_version`,\nthe workflow execution's normal Versioning Behavior and Deployment Version\nare taken from the worker's completion response.\n\nFor example, if the target worker reports Pinned, the execution will remain\npinned after this override is cleared. If the target worker reports\nAutoUpgrade, the execution will resume AutoUpgrade routing after this\noverride is cleared.\n\nIf no Workflow Task completes on `target_deployment_version`, this override\nremains pending." + "description": "Routes Workflow Tasks for this execution to `target_deployment_version`\nuntil a Workflow Task completes on that version, then clears the override.\n\nThis does not force the workflow's normal Versioning Behavior to become\nPinned. After the Workflow Task completes on `target_deployment_version`,\nthe workflow execution's normal Versioning Behavior and Deployment Version\nare taken from the worker's completion response.\n\nFor example, if the target worker reports Pinned, the execution will remain\npinned after this override is cleared. If the target worker reports\nAutoUpgrade, the execution will resume AutoUpgrade routing after this\noverride is cleared.\n\nIf no Workflow Task completes on `target_deployment_version`, this override\nremains pending." }, "VersioningOverridePinnedOverride": { "type": "object", diff --git a/openapi/openapiv3.yaml b/openapi/openapiv3.yaml index 641bc1997..b008d0e9c 100644 --- a/openapi/openapiv3.yaml +++ b/openapi/openapiv3.yaml @@ -18393,8 +18393,8 @@ components: - $ref: '#/components/schemas/WorkerDeploymentVersion' description: Required. Worker Deployment Version to receive the one-time Workflow Task. description: |- - Routes this workflow execution to a specific Worker Deployment Version for one - successful Workflow Task, then clears the override. + Routes Workflow Tasks for this execution to `target_deployment_version` + until a Workflow Task completes on that version, then clears the override. This does not force the workflow's normal Versioning Behavior to become Pinned. After the Workflow Task completes on `target_deployment_version`, diff --git a/temporal/api/workflow/v1/message.proto b/temporal/api/workflow/v1/message.proto index e35f14723..b7989dfc5 100644 --- a/temporal/api/workflow/v1/message.proto +++ b/temporal/api/workflow/v1/message.proto @@ -653,8 +653,8 @@ message VersioningOverride { temporal.api.deployment.v1.WorkerDeploymentVersion version = 2; } - // Routes this workflow execution to a specific Worker Deployment Version for one - // successful Workflow Task, then clears the override. + // Routes Workflow Tasks for this execution to `target_deployment_version` + // until a Workflow Task completes on that version, then clears the override. // // This does not force the workflow's normal Versioning Behavior to become // Pinned. After the Workflow Task completes on `target_deployment_version`, From 0553ec290f223365594c3525f14dbf0347355770 Mon Sep 17 00:00:00 2001 From: Shivam Saraf Date: Sun, 21 Jun 2026 18:50:48 -0400 Subject: [PATCH 5/5] Suppress linter for one-time override field --- openapi/openapiv3.yaml | 2 ++ temporal/api/workflow/v1/message.proto | 2 ++ 2 files changed, 4 insertions(+) diff --git a/openapi/openapiv3.yaml b/openapi/openapiv3.yaml index b008d0e9c..161b651fb 100644 --- a/openapi/openapiv3.yaml +++ b/openapi/openapiv3.yaml @@ -18351,6 +18351,8 @@ components: until one Workflow Task completes there. After completion, the workflow execution's Versioning Behavior and Deployment Version come from the worker's completion response. + (-- api-linter: core::0142::time-field-type=disabled + aip.dev/not-precedent: one_time describes one-time routing semantics, not a timestamp or duration. --) behavior: enum: - VERSIONING_BEHAVIOR_UNSPECIFIED diff --git a/temporal/api/workflow/v1/message.proto b/temporal/api/workflow/v1/message.proto index b7989dfc5..3b015c0e7 100644 --- a/temporal/api/workflow/v1/message.proto +++ b/temporal/api/workflow/v1/message.proto @@ -619,6 +619,8 @@ message VersioningOverride { // until one Workflow Task completes there. After completion, the workflow // execution's Versioning Behavior and Deployment Version come from the // worker's completion response. + // (-- api-linter: core::0142::time-field-type=disabled + // aip.dev/not-precedent: one_time describes one-time routing semantics, not a timestamp or duration. --) OneTimeOverride one_time = 5; }