Workflow Versioning Strategies

Once you have an understanding of the importance of writing deterministic workflow code, you may find yourself grappling with the best way to make changes to that code. Here, I’ll outline a few common strategies and when and how you might employ them.

There are fundamentally three approaches available to you: Task queue based versioning, workflow name based versioning, and the patch/getVersion APIs. Each has its relative merits and demerits. We’re also working towards making task queue based versioning a first-class concept built in to Temporal, but that’s not quite ready as of this writing.

Let’s take a look at each:

Task Queue based Versioning

In this approach, after making changes to your workflow code, you will want to deploy your workers pointed at a new task queue than your existing ones. For example if you previously were targeting the task queue foo-v1, you’d now target foo-v2 or similar. You must also update whatever sources are starting new workflows to point at the new task queue name. Leave your old workers running, possibly reducing the number of instances, until there are no more open workflows on foo. Then you can decommission all of them.


  • Conceptually simple
  • Robust. Changes are isolated from each other in a way that makes mistakes unlikely.


  • Operationally complex (need to keep old workers alive and change what task queue clients point to). This can result in a number of sets of old workers, especially with long running workflows.
  • Can’t be used to fix a bug in currently running/open workflows

Workflow name based Versioning

Very similar to task-queue based versioning, now when you make changes, simply copy your workflow code MyFooWorkflow to MyFooWorkflowV2. You now redeploy all your workers, and change your workflow starters to point at the V2 workflow.


  • Don’t need to keep separate worker fleets pointed at different queues
  • Conceptually simple
  • Easier to patch old versions when necessary without affecting the code for new versions


  • Code duplication - you can only delete the old workflow code when you know all workflows of that type/version have finished
  • Still need to update workflow starters/clients

Patch & GetVersion APIs

We have functions available to you in the SDK which allow you to branch in your workflow code based on whether or not the workflow is running with newer or older code. They take slightly different forms depending on what language you’re using. See the linked docs for more.


  • Don’t need to change where workflow starters are pointing
  • Allows you to change the yet-to-be-executed behavior of currently open workflows while remaining compatible with existing histories. The behavior of new workflows always takes the “new” path.


  • Conceptually complex
  • Cognitive burden of needing to understand how both the “old” and “new” code paths work
  • If used indefinitely on the same workflow definition, can lead to a mess of branching

It’d be great to see this guide updated now that Worker versioning is available. It seems like it would largely replace Task Queued-based versioning, and even some uses of the Patch & GetVersion APIs.

1 Like