Workflow versioning

How Flux versions workflows on each registration, how to pin a run to a specific version, and how to list and delete old versions.

Every time you register a workflow, Flux increments its version number. Older versions stay in the catalog until you remove them. This lets you pin long-running executions to the version they started on, roll back a bad deploy by routing traffic to an earlier version, and audit the full history of what has run in production.

How versioning works

Version numbers are integers starting at 1. The catalog assigns the next version automatically when you call flux workflow register — you never set a version in code.

The first registration produces version 1:

flux workflow register my_workflow.py
# Successfully registered 1 workflow(s) from 'my_workflow.py'.
#   - hello_world (version 1)

Edit the file and register again. The catalog finds an existing row for that namespace and name, increments the counter, and writes a new row alongside the old one:

flux workflow register my_workflow.py
# Successfully registered 1 workflow(s) from 'my_workflow.py'.
#   - hello_world (version 2)

The version counter is scoped to the namespace/name pair. Two workflows with the same name in different namespaces maintain independent counters.

Listing versions

flux workflow versions returns every version of a workflow, newest first:

flux workflow versions hello_world
# Versions of 'hello_world':
# ----------------------------------------
#   Version 2 (id: 9c3f1a...)
#   Version 1 (id: 4e8b2d...)

Add --format json when you need to script against the output or inspect the full metadata:

flux workflow versions hello_world --format json

The JSON response includes the version number, the unique row id, and the registered source for each version.

For workflows in a non-default namespace, qualify the name with the namespace prefix:

flux workflow versions production/hello_world

Inspecting a specific version

flux workflow show defaults to the latest version. Pass --version (or -v) to inspect an earlier one:

flux workflow show hello_world --version 1

This is useful for auditing what code was running during a past execution period.

Running a specific version

flux workflow run defaults to the latest registered version. Pin the run to an earlier version with --version:

flux workflow run hello_world '"Alice"' --version 1

The execution is logged against the version you specified. Inspect it later with flux workflow status <execution-id> to confirm which version ran.

Deleting old versions

Old versions accumulate in the catalog unless you remove them. Delete a specific version with flux workflow delete:

flux workflow delete hello_world --version 1
# Delete workflow 'hello_world' version 1? [y/N]: y
# Successfully deleted workflow 'hello_world' version 1.

Delete all versions of a workflow (remove it entirely):

flux workflow delete hello_world
# Delete workflow 'hello_world' (all versions)? [y/N]: y
# Successfully deleted workflow 'hello_world' (all versions).

Skip the confirmation prompt in automation with --force:

flux workflow delete hello_world --version 1 --force

Version pinning in practice

A typical promotion sequence:

  1. Register the updated workflow — Flux assigns the next version number.
  2. Verify the new version by running a test execution against it with --version N.
  3. Once satisfied, route new production runs to the default (latest) version.
  4. After all in-flight executions on the old version complete, delete the old version to keep the catalog clean.

There is no API flag to “make version 2 the default”; the latest version is always the default. To route new runs to an older version, pass --version at every call site.

What’s next