Engine Version

A workflow can declare the engine version it needs, so an out-of-date orchstep fails fast with a clear message instead of a confusing mid-run error. It's the analog of Terraform's required_version, package.json's engines, or go.mod's go directive.

name: deploy
required:
  orchstep: ">=1.2.0"
tasks:
  ...

required is its own top-level block - deliberately not under config:, because config: is behavior settings that can also be loaded from a machine-level file, while a version requirement must travel with the committed workflow. It's optional: a workflow with no required runs on whatever engine you have.

Constraint syntax

Standard semver constraints (same as module versions):

What happens on a mismatch

If the running engine doesn't satisfy the constraint, the run fails before executing anything:

$ orchstep run deploy
Error: workflow requires orchstep >=1.2.0, but this engine is 1.0.0;
upgrade orchstep, or pass --ignore-version-check to override

• Escape hatch: --ignore-version-check (or ORCHSTEP_IGNORE_VERSION_CHECK=1) downgrades the error to a warning and runs anyway.
• Dev builds: a locally-built/unstamped engine reports dev and skips the check (there's nothing meaningful to compare).

Modules can require an engine too

A module declares the same required block in its orchstep-module.yml (or a single-file module). Pulling a module built for a newer engine into an older one fails clearly at load time:

Error: module 'deploy-kit' requires orchstep >=2.0.0, but this engine is 1.4.0; ...

In a chain (workflow → modules → nested modules) there's nothing to resolve - there's one engine, so OrchStep simply checks that it satisfies every requirement in the chain (the most restrictive wins).

Testing and diagnostics

ORCHSTEP_VERSION_OVERRIDE sets the version used for the check, so you can test the gate - or answer "would this run on 1.0?" - without installing another engine:

ORCHSTEP_VERSION_OVERRIDE=1.0.0 orchstep run deploy   # simulate an old engine

Editor support

The JSON Schema includes required.orchstep, so editors autocomplete the field and flag typos.