Skip to main content

Version and deploy a workflow

Editing a workflow saves a new version; running it in an environment is a separate step called deployment. Keeping these separate lets you test a change before it reaches production.

What this solves

If editing a workflow immediately changes what runs in production, there's no safe way to test a change first, and no clean way back when one goes wrong.

Versions​

Committing a change creates a new version, with notes and full history. You can review earlier versions and roll back to one. The older versions are never lost.

Draft, save, version — which is which​

The editor keeps these apart deliberately, because only one of them puts your work on the server:

  • A draft is local. Your edits auto-save in this browser as a temporary draft. Nobody else sees them, and they are not on the server. The Workflow Settings panel's footer says so.
  • Committing a version is the save that counts. Use the filled save action in the toolbar — it's the only filled icon in that row, and its tooltip reads Commit changes to a version.
  • The version selector tells you where you stand: v1 (draft) means nothing has been committed yet, v1 means committed and clean, and v1 (auto saved draft) means committed with local edits that are not on the server.

The very first version commits with no dialog — there's no history to describe yet. Every one after that asks for Notes, which are required and capped at 300 characters. They used to be optional, which is why older version histories mostly say nothing.

Committing a sub-workflow tells you who else it affects

If the workflow is marked Sub-Workflow, the dialog leads with "Changes will impact all workflows that use this as a sub-workflow" and names the parents that embed it — the first three, then a count of the rest. Those parents change behaviour on their next build, so read the list before you commit.

It never blocks Save: if the parents can't be looked up, you get the sentence without the names rather than no warning at all. The save that turns Sub-Workflow off warns too — that's the edit those parents most need to know about. Only container embeddings count; a cross-workflow dependency on this workflow isn't one. See Saving a version warns you which parents it affects.

If the footer turns red

That means the browser couldn't store the draft — storage is full or unavailable. Your edits are still on screen but nothing is persisted anywhere. Commit a version now.

If a commit is refused because of a sub-workflow​

A deployment set to LATEST re-points at whatever you commit next, so a commit that changes which sub-workflows a workflow embeds can break the environments running it. That commit is now refused rather than allowed through, and the Save to a New Version dialog tells you before you save: "This version cannot be saved while deployed as 'latest'.", with one line per environment naming the job and the sub-workflow at fault, and Save disabled.

The way out is either to deploy the sub-workflow to those environments or to pin this workflow's deployment there, then save again. Two things worth knowing:

  • A save that leaves the container references alone is never checked, so a workflow whose sub-workflow was never deployed stays editable for every other edit you need to make to repair it.
  • A check that can't be reached doesn't block you. The dialog says the save will be verified on submit and leaves Save live; the server has the last word either way.

The dialog now stays open until the commit settles, so a refusal arrives in place with your notes still in it. Restore goes through the same check with no dialog, and reports the first problem with the rest counted.

See Committing a version is checked too.

If Create Version is greyed out​

Create Version is blocked while the workflow contains a job that couldn't run. Hover the button: the tooltip names the first problem and how many others there are, and the job responsible is outlined in red on the canvas — hover that too for its own reason.

The usual causes are a job with no job type (most often one dropped straight onto the canvas and not filled in), a missing required parameter or custom field, a duplicate job name, a job type that isn't available in this workspace, or a job that needs an agent assignment and has none.

Fix the flagged jobs and the button re-enables. Two things that surprise people:

  • It can flag a job you didn't touch. The check covers the whole workflow, so a job stored before a rule applied — or before a plugin update made one more parameter required — has to be completed now. That's deliberate: the alternative is a version that fails when it runs.

If the tooltip says Checking workflow…, the check is still loading its data — wait a moment. If it says it couldn't load the job types, retry.

Deploy to an environment​

Deploy a workflow to an environment and choose how it tracks versions:

  • Latest: the environment always runs the newest version.
  • Pinned: the environment runs a fixed version until you change it.

You can also set an effective date and expiration date so a deployment is active only within a window. The same workflow can be deployed to several environments at once: for example, pinned to a tested version in production while running latest in a test environment.

Good to know
  • A change isn't appearing in an environment? The deployment is probably pinned to an older version, the new version hasn't been deployed, or the effective date is in the future.
  • Deliberate production-vs-test drift is normal: pin production, run latest in test.
A workflow with a container job deploys with its sub-workflows, or not at all

If the workflow embeds another through a Workflow Container job, you cannot deploy it to an environment where that sub-workflow is not deployed — nor for dates the sub-workflow's own deployment doesn't cover. The Deploy modal shows the state per environment in a Sub-Workflows section and holds Set-up Deployment back with the reason on the card, so deploy the sub-workflow first.

The rule runs the other way too: once a parent is deployed, the sub-workflow's deployment can't be removed or narrowed underneath it, and the sub-workflow can't be renamed or deleted. A Used By section on the sub-workflow's card names the parents holding it in place. See A sub-workflow must be deployed wherever its parent is.

The deploy form checks the dates you type, as you type them. The New Deploy and Edit Deploy form carries the same Sub-Workflows section and re-checks it against the environment, strategy, pinned version and window you have entered, so you find out that a date doesn't fit before you submit it. Deploy stays inactive until it does, and tells you why on the button. More on the form's check.

Renaming a frequency as part of a deployment

A rename carries through to the jobs bound to that frequency, so their schedule survives the deployment. The dialog blocks a rename it cannot apply cleanly — two renames landing on the same name, a chain of renames, or a name already in use — so resolve the conflict and deploy again.

Related topics