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

# Workflow Versioning

> How workflow versions are numbered, what each version bump means, and how to pin a run to a version

Every time a workflow is saved, the new version gets a semantic version number, `MAJOR.MINOR.PATCH`. The number is based on how the version's input and output schemas changed compared with the version it was saved from. You pin a run to a version or a range with `workflow_version` on [Start a Run](/run-api/start-a-run) or in the SDKs.

## What each bump means

A save takes the most severe bump of all the changes it contains. One major-level change makes the whole save a major bump.

| Change | Bump |
| - | - |
| Required input added | Major |
| Input removed | Major |
| Optional input made required | Major |
| Input type changed | Major |
| Output removed | Major |
| Output type changed | Major |
| Optional input added | Minor |
| Required input made optional | Minor |
| Output added | Minor |
| No schema change, for example a fix, a selector update or a newly handled edge case | Patch |

## What the version number does not cover

* Only top-level fields are compared. A change inside a nested object, such as a field added to or removed from an object-typed output, is versioned as a patch. So are changes to enums, formats, patterns and descriptions.
* An output changing from optional to required is versioned as a patch.
* The number describes the schema, not behavior. A patch can still change how the workflow navigates a site or which values it extracts.
* The bump is suggested automatically from the schema diff. The person saving the version can override it.

## Pinning a run

Set at most one of these on a run. Without a pin, a run executes the latest version on the workflow's default branch.

| Pin | Example | Runs | Use it when |
| - | - | - | - |
| None | | The default branch's latest version | You always want the newest version |
| Major range | `"2.x"` | The highest `2.x.x` version | You want fixes automatically but no major schema changes |
| Exact version | `"2.4.1"` | Exactly that version | You want to review every change and upgrade by hand |
| `workflow_branch_id` | | That branch's latest version | You are testing a branch before it is merged |

`workflow_version` accepts any range the [semver](https://github.com/npm/node-semver#ranges) package understands, including `"^2.4.0"`, `"~2.4.0"`, `"2.4.x"` and `">=2.4.0 <3.0.0"`. The highest matching version runs.

<Warning>
  A range matches versions saved on any branch, not only the default branch. Version numbers are shared across all branches, so a version saved on an unmerged branch can be the highest match for your range.
</Warning>

## Versions saved before semantic versioning

Workflows versioned before semantic versions were introduced had each version number `N` become `N.0.0`. A run pinned with the legacy `workflow_version_number: N` behaves like `workflow_version: "N.x"`, so it also picks up later `N.x.x` versions.

## Listing versions

Use [List Versions](/workflow-api/list-versions) or the SDKs ([JavaScript](/sdk/js/workflows#versions-and-branches), [Python](/sdk/python/workflows#versions-and-branches)) to see each version's number, branch and note.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.