Skip to main content
A variant is a named way to run a pipeline. Every pipeline run executes exactly one variant — you choose it when you start the run from the dashboard, CLI, or API, or a trigger selects it for you. Instead of maintaining a separate pipeline per environment, define the steps once and add a variant for each environment:

​
Reuse one pipeline for multiple environments

Steps reference the current variant with << pipeline.variant.id >> and << pipeline.variant.name >> template expressions. Name your variant IDs after your environment given IDs, and one set of steps deploys to whichever environment the run targets:
Triggering the production variant resolves module_instance to production.web-app; the staging variant resolves it to staging.web-app.

​
Hard-code input values per variant

A variant’s input map locks specific pipeline inputs to fixed values. Locked values cannot be overridden by triggers or at run time — attempting to override one fails validation with variant_locked_override.
Use this to guarantee environment-specific settings — the production variant always runs CI steps in the prod-builders execution environment, no matter how the run is started. Input values resolve with this precedence:
  1. Variant hard-coded input values
  2. Values provided when the run starts — manually or from a trigger’s run config
  3. The input’s default
Every key in a variant’s input map must match a declared input under top-level inputs. If any variant or trigger provides input values, the pipeline must declare explicit inputs.

​
Triggers select a variant

A trigger’s run map is keyed by variant ID, so one trigger can start runs for one or more variants — each with its own input values:
Every variant ID in run must match a declared variant, and any required input without a default must be satisfied by the variant’s hard-coded values or the trigger’s run inputs.

​
Schema reference

See VariantDefinition for every field.