Skip to main content
Pipeline configuration defines steps, parallel and group blocks, inputs, variants, and triggers. Use this reference when you write pipeline config files or validate generated pipeline definitions. See Pipeline config file to pull, edit, and apply a pipeline config from a version-controllable file, For a compact, machine-readable version, fetch https://api.ravion.com/pipelines/schema.md.
Pipeline builder configs still include nixpacks for existing pipelines, but it is deprecated. Use railpack for new build:image and build:static steps.

Legend

PipelineConfig

Pipeline configuration - the top-level schema
triggers
PipelineTrigger[]
Webhook triggers that automatically start pipeline runs on events like git pushSee: PipelineTrigger
inputs
PipelineInputDefinition[]
User-configurable inputs that can vary per run — environment name, image tag, feature flags, etcSee: PipelineInputDefinition
variants
VariantDefinition[]
required
Deployment variants such as production, staging, or dev — each variant can lock specific input valuesSee: VariantDefinition
steps
Step[]
required
Ordered list of steps to execute — steps run sequentially unless wrapped in a parallel blockSee: Step(minItems:1)
rollback
Step[]
Steps to execute if the pipeline fails — runs in order after a failure is detectedSee: Step

Triggers

Webhook triggers that automatically start pipeline runs on events like git push

PipelineTrigger

Pipeline trigger definition.Discriminated union. The type field selects which schema applies.

GenericPipelineTrigger

Pipeline trigger for generic webhooks.
id
string
required
Unique identifier for this trigger
repo
string
required
Git repository in owner/repo or host/owner/repo format(templateable)
filter
TriggerFilter
Filters to narrow which events trigger the pipelineSee: TriggerFilter
run
map<string,TriggerRunVariantConfig>
required
Maps variant IDs to run configuration — keys must match declared variant IDs.See: TriggerRunVariantConfig
type
enum
required
Webhook type for generic webhook triggers.Allowed values: webhook

GithubPipelineTrigger

Pipeline trigger for GitHub webhooks.
id
string
required
Unique identifier for this trigger
repo
string
required
Git repository in owner/repo or host/owner/repo format(templateable)
filter
TriggerFilter
Filters to narrow which events trigger the pipelineSee: TriggerFilter
run
map<string,TriggerRunVariantConfig>
required
Maps variant IDs to run configuration — keys must match declared variant IDs.See: TriggerRunVariantConfig
type
enum
required
Webhook type — determines which events are supported.Allowed values: webhook:github
event
enum
required
Webhook event type to listen for.Allowed values: push | pull_request | pull_request_review | pull_request_review_comment | pull_request_review_thread | release | deployment

GitlabPipelineTrigger

Pipeline trigger for GitLab webhooks.
id
string
required
Unique identifier for this trigger
repo
string
required
Git repository in owner/repo or host/owner/repo format(templateable)
filter
TriggerFilter
Filters to narrow which events trigger the pipelineSee: TriggerFilter
run
map<string,TriggerRunVariantConfig>
required
Maps variant IDs to run configuration — keys must match declared variant IDs.See: TriggerRunVariantConfig
type
enum
required
Webhook type — determines which events are supported.Allowed values: webhook:gitlab
event
enum
required
Webhook event type to listen for.Allowed values: push | merge_request | tag_push

TriggerFilter

Trigger filter configuration
branch
string | null
Only trigger when this branch is pushed(templateable)
tag
string | null
Only trigger when a tag matching this pattern is pushed(templateable)
action
string | string[]
Only trigger for specific webhook actions.(templateable)
paths
string[] | null
Only trigger when files in these paths are changed(templateable)
payload
PayloadCondition[]
Filter by webhook payload fields using dot-notation paths.See: PayloadCondition

TriggerRepo

Git repository identifier used by webhook triggers.Type: string

TriggerRunVariantConfig

Per-variant run configuration for a trigger.
description
string | null
Description for the pipeline run created by this trigger variant(templateable)
input
map<string,any | null>
Input overrides for this variant run(templateable)

GithubWebhookEvent

GitHub webhook events that can trigger a pipelineAllowed values:
  • push
  • pull_request
  • pull_request_review
  • pull_request_review_comment
  • pull_request_review_thread
  • release
  • deployment

GitlabWebhookEvent

GitLab webhook events that can trigger a pipelineAllowed values:
  • push
  • merge_request
  • tag_push

PayloadCondition

Condition to check against a webhook payload field.
path
string
required
Dot-notation path to the payload field
equals
string | null
Exact string match(templateable)
contains
string | null
Substring match(templateable)
matches
string | null
Glob pattern match(templateable)
one_of
string[] | null
Value must be one of these strings(templateable)
not
PayloadConditionMatcher
Negated payload field matcher. The condition fails when this matcher is true.See: PayloadConditionMatcher

PayloadConditionMatcher

Payload field matcher used by positive conditions and negated conditions.
equals
string | null
Exact string match(templateable)
contains
string | null
Substring match(templateable)
matches
string | null
Glob pattern match(templateable)
one_of
string[] | null
Value must be one of these strings(templateable)

Inputs

User-configurable inputs that can vary per run — environment name, image tag, feature flags, etc

PipelineInputDefinition

Union of all pipeline input definitions, discriminated by type.Discriminated union. The type field selects which schema applies.

PipelineBooleanInputDefinition

Boolean pipeline input definition
id
string
required
Unique identifier for this input — used in << pipeline.input.key >> templates(minLen:1)
type
enum
required
Input type — determines the field widget and validation rulesAllowed values: boolean
required
boolean
default:"true"
Whether this input must be provided when running the pipeline
description
string
Human-readable description shown in the UI when running the pipeline
default
boolean
Default value used when no value is provided at runtime

PipelineNumberInputDefinition

Number pipeline input definition
id
string
required
Unique identifier for this input — used in << pipeline.input.key >> templates(minLen:1)
type
enum
required
Input type — determines the field widget and validation rulesAllowed values: number
required
boolean
default:"true"
Whether this input must be provided when running the pipeline
description
string
Human-readable description shown in the UI when running the pipeline
default
integer
Default value used when no value is provided at runtime(format:int32)
values
Module.NumberValueItem[]
Dropdown options restricting allowed valuesSee: Module.NumberValueItem
min
integer
Minimum allowed value (inclusive)(format:int32)
max
integer
Maximum allowed value (inclusive)(format:int32)

PipelineObjectInputDefinition

Object pipeline input definition
id
string
required
Unique identifier for this input — used in << pipeline.input.key >> templates(minLen:1)
type
enum
required
Input type — determines the field widget and validation rulesAllowed values: object
required
boolean
default:"true"
Whether this input must be provided when running the pipeline
description
string
Human-readable description shown in the UI when running the pipeline
default
any
Default value used when no value is provided at runtime

PipelineStringArrayInputDefinition

String array pipeline input definition
id
string
required
Unique identifier for this input — used in << pipeline.input.key >> templates(minLen:1)
type
enum
required
Input type — determines the field widget and validation rulesAllowed values: string_array
required
boolean
default:"true"
Whether this input must be provided when running the pipeline
description
string
Human-readable description shown in the UI when running the pipeline
default
string[]
Default value used when no value is provided at runtime
patterns
Module.ValidationPattern[]
Regex patterns each array element must matchSee: Module.ValidationPattern

PipelineStringInputDefinition

String pipeline input definition
id
string
required
Unique identifier for this input — used in << pipeline.input.key >> templates(minLen:1)
type
enum
required
Input type — determines the field widget and validation rulesAllowed values: string
required
boolean
default:"true"
Whether this input must be provided when running the pipeline
description
string
Human-readable description shown in the UI when running the pipeline
default
string
Default value used when no value is provided at runtime
values
Module.StringValueItem[]
Dropdown options restricting allowed valuesSee: Module.StringValueItem
patterns
Module.ValidationPattern[]
Regex patterns the value must matchSee: Module.ValidationPattern

PipelineTextInputDefinition

Text pipeline input definition
id
string
required
Unique identifier for this input — used in << pipeline.input.key >> templates(minLen:1)
type
enum
required
Input type — determines the field widget and validation rulesAllowed values: text
required
boolean
default:"true"
Whether this input must be provided when running the pipeline
description
string
Human-readable description shown in the UI when running the pipeline
default
string
Default value used when no value is provided at runtime
patterns
Module.ValidationPattern[]
Regex patterns the value must matchSee: Module.ValidationPattern

Module.NumberValueItem

A selectable option with a numeric value.
label
string
Text shown in the dropdown
description
string
Extra detail shown alongside the option
group_label
string
Groups options under a shared heading in the dropdown
value
integer
required
Actual number sent to Terraform when this option is selected(format:int32)
show_when
Module.ShowWhen
Only show this option when another field has a specific valueSee: Module.ShowWhen

Module.ValidationPattern

A regex pattern with an error message for validation
pattern
string
required
JavaScript regex the input must match
message
string
required
Error shown to the user when validation fails

Module.StringValueItem

A selectable option with a string value.
label
string
Text shown in the dropdown
description
string
Extra detail shown alongside the option
group_label
string
Groups options under a shared heading in the dropdown
value
string
required
Actual value sent to Terraform when this option is selected
show_when
Module.ShowWhen
Only show this option when another field has a specific valueSee: Module.ShowWhen

Module.ShowWhen

Conditional visibility mapping; array source values support contains and contains-all matching.Type: map<string,Module.ShowWhenCondition>

Module.ShowWhenCondition

A show_when condition.One of: string | integer | boolean | string | integer | boolean[], Module.ShowWhenNotCondition.

Module.ShowWhenComparableValue

Value or values to compare against in a show_when condition; arrays mean membership for scalar sources and contains-all for array sources.One of: string | integer | boolean, string | integer | boolean[].

Module.ShowWhenNotCondition

Negated show_when condition.
not
string | integer | boolean | string | integer | boolean[]
required
Show the property only when the source value does not match this condition.

Module.ShowWhenValue

Value that can be used in a show_when condition.One of: string, integer, boolean.

Variants

Deployment variants such as production, staging, or dev — each variant can lock specific input values

VariantDefinition

Variant definition
id
string
required
Unique identifier for this variant, referenced by triggers(minLen:1)
name
string
required
Display name shown in the UI(minLen:1)
input
map<string,any | null>
Hard-coded input values for this variant — keys must match declared inputs, cannot be overridden by triggers

Steps

Ordered list of steps to execute — steps run sequentially unless wrapped in a parallel block

Step

Step - can be action, parallel, or group.One of: ActionStep, ParallelStep, GroupStep.

ActionStep

Union of all action step types.Discriminated union. The type field selects which schema applies.

GroupStep

Group step - contains nested steps
group
string
required
Human-readable group label shown in pipeline UI
steps
Step[]
required
See: Step(minItems:1)
concurrency
ConcurrencyConfig
Concurrency configuration for executions within this groupSee: ConcurrencyConfig

ParallelStep

Parallel step - executes children concurrently
parallel
ParallelChild[]
required
See: ParallelChild(minItems:1)
concurrency
ConcurrencyConfig
Concurrency configuration for executions within this parallel blockSee: ConcurrencyConfig
fail_strategy
enum
default:"cancel-all"
How to handle failures while branches in this parallel block are runningAllowed values: cancel-all | finish-running | finish-all

ApprovalStep

Approval action step — pauses pipeline execution until a user explicitly approves. If timeout is omitted, the step waits indefinitely.
id
string
required
Unique step identifier, used for referencing in logs and dependencies(minLen:1)
name
string
Human-readable step name shown in the pipeline UI
timeout
integer | null
Maximum execution time in seconds before the step is killed(format:int32,min:1; templateable)
if
boolean | null
Condition that must evaluate to true for this step to run Accepts either a boolean literal or a full template token that resolves to a boolean(templateable)
concurrency
ConcurrencyConfig
Concurrency configuration for controlling step execution across variantsSee: ConcurrencyConfig
type
enum
required
Allowed values: approval

BuildImageCiStep

Build image CI action step
id
string
required
Unique step identifier, used for referencing in logs and dependencies(minLen:1)
name
string
Human-readable step name shown in the pipeline UI
timeout
integer | null
Maximum execution time in seconds before the step is killed(format:int32,min:1; templateable)
if
boolean | null
Condition that must evaluate to true for this step to run Accepts either a boolean literal or a full template token that resolves to a boolean(templateable)
concurrency
ConcurrencyConfig
Concurrency configuration for controlling step execution across variantsSee: ConcurrencyConfig
type
enum
required
Allowed values: build:image
source
GitSource
required
Git source configurationSee: GitSource(templateable)
builder
ImageBuildConfig
required
Builder configuration — dockerfile, nixpacks, or railpack settings for image buildsSee: ImageBuildConfig(templateable)
environment_variables
EnvironmentVariablesValue
Environment variables available during the build — plain strings or AWS secret referencesSee: EnvironmentVariablesValue(templateable)
debug
boolean | null
Enable verbose build output for debugging build issues Accepts either a boolean literal or a full template token(templateable)
destinations
EcrDestination[]
required
ECR destinations where the built Docker image will be pushedSee: EcrDestination(minItems:1; templateable)
infrastructure
StepInfrastructure
required
Execution environment configuration — required because image builds run on provisioned computeSee: StepInfrastructure(templateable)

BuildStaticCiStep

Build static CI action step
id
string
required
Unique step identifier, used for referencing in logs and dependencies(minLen:1)
name
string
Human-readable step name shown in the pipeline UI
timeout
integer | null
Maximum execution time in seconds before the step is killed(format:int32,min:1; templateable)
if
boolean | null
Condition that must evaluate to true for this step to run Accepts either a boolean literal or a full template token that resolves to a boolean(templateable)
concurrency
ConcurrencyConfig
Concurrency configuration for controlling step execution across variantsSee: ConcurrencyConfig
type
enum
required
Allowed values: build:static
source
GitSource
required
Git source configurationSee: GitSource(templateable)
builder
StaticBuildConfig
required
Builder configuration — dockerfile, nixpacks, or railpack settingsSee: StaticBuildConfig(templateable)
environment_variables
EnvironmentVariablesValue
Environment variables available during the build — plain strings or AWS secret referencesSee: EnvironmentVariablesValue(templateable)
debug
boolean | null
Enable verbose build output for debugging build issues Accepts either a boolean literal or a full template token(templateable)
destinations
S3Destination[]
required
S3 destinations where the built static assets will be uploadedSee: S3Destination(minItems:1; templateable)
infrastructure
StepInfrastructure
required
Execution environment configuration — required because static builds run on provisioned computeSee: StepInfrastructure(templateable)

BuildStep

General-purpose build action step — triggers a build based on the module’s build config.
id
string
required
Unique step identifier, used for referencing in logs and dependencies(minLen:1)
name
string
Human-readable step name shown in the pipeline UI
timeout
integer | null
Maximum execution time in seconds before the step is killed(format:int32,min:1; templateable)
if
boolean | null
Condition that must evaluate to true for this step to run Accepts either a boolean literal or a full template token that resolves to a boolean(templateable)
module_instance
string
required
Module instance reference — accepts the module instance row ID (e.g. mi_…), environmentGivenId.moduleGivenId, or `projectGivenId.environmentGivenId.modul…(minLen:1; templateable)
description
string | null
Human-readable description of this deployment.(templateable)
type
enum
required
Allowed values: build
input
map<string,any | null>
User-defined build parameters passed through to the module build manager.(templateable)

CustomCommandCiStep

Custom command CI action step
id
string
required
Unique step identifier, used for referencing in logs and dependencies(minLen:1)
name
string
Human-readable step name shown in the pipeline UI
timeout
integer | null
Maximum execution time in seconds before the step is killed(format:int32,min:1; templateable)
if
boolean | null
Condition that must evaluate to true for this step to run Accepts either a boolean literal or a full template token that resolves to a boolean(templateable)
setup
SetupAction[] | null
Setup actions to install tools before the commands run, in order, before any command.See: SetupAction(templateable)
concurrency
ConcurrencyConfig
Concurrency configuration for controlling step execution across variantsSee: ConcurrencyConfig
type
enum
required
Allowed values: custom
source
GitSource
Git source configurationSee: GitSource(templateable)
commands
string[]
required
Shell commands to execute in order(minItems:1; templateable)
environment_variables
EnvironmentVariablesValue
Environment variables available during command executionSee: EnvironmentVariablesValue(templateable)
infrastructure
StepInfrastructure
required
Execution environment configuration — required because custom commands run on provisioned computeSee: StepInfrastructure(templateable)

DeployStep

General-purpose deploy action step — triggers a deployment based on the module’s deployment config.
id
string
required
Unique step identifier, used for referencing in logs and dependencies(minLen:1)
name
string
Human-readable step name shown in the pipeline UI
timeout
integer | null
Maximum execution time in seconds before the step is killed(format:int32,min:1; templateable)
if
boolean | null
Condition that must evaluate to true for this step to run Accepts either a boolean literal or a full template token that resolves to a boolean(templateable)
module_instance
string
required
Module instance reference — accepts the module instance row ID (e.g. mi_…), environmentGivenId.moduleGivenId, or `projectGivenId.environmentGivenId.modul…(minLen:1; templateable)
description
string | null
Human-readable description of this deployment.(templateable)
type
enum
required
Allowed values: deploy
input
map<string,any | null>
User-defined deploy parameters passed through to the deploy manager.(templateable)

RollbackStep

Rollback action step — reverts a module to a specific previous deployment.
id
string
required
Unique step identifier, used for referencing in logs and dependencies(minLen:1)
name
string
Human-readable step name shown in the pipeline UI
timeout
integer | null
Maximum execution time in seconds before the step is killed(format:int32,min:1; templateable)
if
boolean | null
Condition that must evaluate to true for this step to run Accepts either a boolean literal or a full template token that resolves to a boolean(templateable)
type
enum
required
Allowed values: rollback
deployment_id
string
required
Deployment ID to rollback to(minLen:1; templateable)

SleepStep

Sleep action step — pauses pipeline execution for testing and debugging
id
string
required
Unique step identifier, used for referencing in logs and dependencies(minLen:1)
name
string
Human-readable step name shown in the pipeline UI
timeout
integer | null
Maximum execution time in seconds before the step is killed(format:int32,min:1; templateable)
if
boolean | null
Condition that must evaluate to true for this step to run Accepts either a boolean literal or a full template token that resolves to a boolean(templateable)
concurrency
ConcurrencyConfig
Concurrency configuration for controlling step execution across variantsSee: ConcurrencyConfig
type
enum
required
Allowed values: sleep
duration_ms
integer
required
Sleep duration in milliseconds(format:int64; templateable)

TerraformApplyCiStep

Terraform apply CI action step
id
string
required
Unique step identifier, used for referencing in logs and dependencies(minLen:1)
name
string
Human-readable step name shown in the pipeline UI
timeout
integer | null
Maximum execution time in seconds before the step is killed(format:int32,min:1; templateable)
if
boolean | null
Condition that must evaluate to true for this step to run Accepts either a boolean literal or a full template token that resolves to a boolean(templateable)
concurrency
ConcurrencyConfig
Concurrency configuration for controlling step execution across variantsSee: ConcurrencyConfig
type
enum
required
Allowed values: terraform:apply
source
GitSource
Git source configuration — if omitted, uses the trigger’s repositorySee: GitSource(templateable)
environment_variables
EnvironmentVariablesValue
Environment variables available during execution — plain strings or AWS secret referencesSee: EnvironmentVariablesValue(templateable)
tool
enum
required
IaC tool implementation used to execute this stepAllowed values: opentofu | terraform(templateable)
version
string
required
Terraform/OpenTofu version to execute(minLen:1; templateable)
stack_id
string | null
Stack ID used for terraform resource/execution tracking Automatically set when triggered from a stack(templateable)
plan_file_uri
string
required
S3 URI of the plan file to apply — typically from a preceding plan step output (e.g. s3://bucket/path/to/plan.tfplan)(templateable)
infrastructure
StepInfrastructure
required
Execution environment configuration — required because Terraform apply runs on provisioned computeSee: StepInfrastructure(templateable)

TerraformPlanCiStep

Terraform plan CI action step
id
string
required
Unique step identifier, used for referencing in logs and dependencies(minLen:1)
name
string
Human-readable step name shown in the pipeline UI
timeout
integer | null
Maximum execution time in seconds before the step is killed(format:int32,min:1; templateable)
if
boolean | null
Condition that must evaluate to true for this step to run Accepts either a boolean literal or a full template token that resolves to a boolean(templateable)
concurrency
ConcurrencyConfig
Concurrency configuration for controlling step execution across variantsSee: ConcurrencyConfig
type
enum
required
Allowed values: terraform:plan
source
GitSource
Git source configuration — if omitted, uses the trigger’s repositorySee: GitSource(templateable)
environment_variables
EnvironmentVariablesValue
Environment variables available during execution — plain strings or AWS secret referencesSee: EnvironmentVariablesValue(templateable)
tool
enum
required
IaC tool implementation used to execute this stepAllowed values: opentofu | terraform(templateable)
version
string
required
Terraform/OpenTofu version to execute(minLen:1; templateable)
stack_id
string | null
Stack ID used for terraform resource/execution tracking Automatically set when triggered from a stack(templateable)
terraform_variables
TerraformVariablesValue
Terraform input variables written to a .auto.tfvars.json file during plan creation — supports all HCL types and AWS secret referencesSee: TerraformVariablesValue(templateable)
terraform_variable_files
string[] | null
Terraform tfvars file paths passed to terraform plan as -var-file flags, in the configured order.(templateable)
plan_file_directory_uri
string | null
S3 directory URI to upload the plan file to — overrides the default convention-based path (e.g. s3://bucket/terraform-plans/run-123)(templateable)
plan_type
enum
default:"apply"
Type of plan to generate — “apply” (default) creates/updates resources, “destroy” tears them downAllowed values: apply | destroy(templateable)
infrastructure
StepInfrastructure
required
Execution environment configuration — required because Terraform plan runs on provisioned computeSee: StepInfrastructure(templateable)

TriggerPipelineStep

Trigger pipeline action step
id
string
required
Unique step identifier, used for referencing in logs and dependencies(minLen:1)
name
string
Human-readable step name shown in the pipeline UI
timeout
integer | null
Maximum execution time in seconds before the step is killed(format:int32,min:1; templateable)
if
boolean | null
Condition that must evaluate to true for this step to run Accepts either a boolean literal or a full template token that resolves to a boolean(templateable)
concurrency
ConcurrencyConfig
Concurrency configuration for controlling step execution across variantsSee: ConcurrencyConfig
type
enum
required
Allowed values: trigger:pipeline
pipeline_id
string
required
ID of the pipeline to trigger(minLen:1; templateable)
pipeline_version_id
string | null
Specific pipeline version to trigger(templateable)
description
string
required
Description to use for the triggered pipeline run(minLen:1; templateable)
inputs
map<string,any | null>
Input values to pass to the triggered pipeline as key-value pairs(templateable)
run
map<string,TriggerRunVariantConfig> | null
Per-variant run overrides — keys are variant IDs, values include description and optional input overridesSee: TriggerRunVariantConfig(templateable)

ConcurrencyConfig

Concurrency configuration for controlling parallel execution
key
string
Unique identifier for the concurrency scope within this pipeline Steps/blocks with the same key share a concurrency limit Keys are scoped to org + pipeline —…
value
integer
default:"0"
Maximum concurrent executions allowed (0 means unlimited, 1 means sequential)(format:int32,min:0)
behavior
enum
default:"queue"
Behavior when the concurrency limit is reachedAllowed values: queue | cancel-in-progress
queue_size
integer
Maximum queue size when behavior is “queue” Only applies when behavior is “queue” Unset means unlimited queue depth 0 disables queueing when behavior is “queue”(format:int32,min:0)
queue_overflow_discard
enum
default:"oldest"
Which items to discard when queue overflows Only applies when behavior is “queue” and queue_size > 0Allowed values: oldest | newest

ParallelChild

Parallel child - can be action or group (no nested parallel allowed)One of: ActionStep, GroupStep.

ParallelFailStrategy

Strategy for handling failures within a parallel blockAllowed values:
  • cancel-all
  • finish-running
  • finish-all

EcrDestination

ECR destination for image builds
id
string
required
Unique destination identifier within the build step(templateable)
type
enum
required
ECR destination typeAllowed values: ecr(templateable)
repository_arn
string
required
ECR repository ARN(templateable)
tags
string[] | null
Docker image tags to apply in ECR after the build finishes(templateable)

EnvironmentVariablesValue

Environment variable map value.One of: map<string,EnvironmentVariable>, string.

GitSource

Git source configuration for fetching code
type
enum
required
Source type identifierAllowed values: git(templateable)
repo
string
required
Full repository URL including host(templateable)
branch
string
required
Branch to check out(minLen:1; templateable)
ref
string | null
Git ref to check out — branch, commit SHA, tag, or other ref. Overrides branch HEAD if set.(templateable)
base_path
string | null
default:"."
Base path within the repository to use as the working root(templateable)

ImageBuildConfig

Image build configuration — discriminated by build methodDiscriminated union. The type field selects which schema applies.

StepInfrastructure

Step infrastructure configuration
execution_environment_id
string | null
ID or given ID of a pre-configured execution environment(templateable)
aws_account_id
string | null
AWS account reference for automatic network selection.(templateable)
region
string | null
AWS region for automatic network selection(templateable)
type
enum
required
Instance type — “ec2” for on-demand or “ec2-spot” for cheaper spot instancesAllowed values: ec2 | ec2-spot(templateable)
instance_size
string | string[]
required
Instance size — a single size like “large” or an array like [“large”, “xlarge”] for spot fallback(templateable)
ami
string | null
AMI ID for the runner instance(templateable)
permissions
AwsPermissions
IAM permissions for the runner role — “attach” to add policies or “replace” to override step defaultsSee: AwsPermissions(templateable)
storage
StorageConfig
Root volume storage configurationSee: StorageConfig(templateable)

S3Destination

S3 destination for build artifacts
id
string
required
Unique destination identifier within the build step(minLen:1; templateable)
type
enum
required
S3 destination typeAllowed values: s3(templateable)
bucket
string
required
S3 bucket name where built assets will be uploaded(templateable)
directory
string | null
S3 directory override for the uploaded build output.(templateable)
region
string
required
AWS region for the destination S3 bucket(templateable)

StaticBuildConfig

Static build configuration — discriminated by build methodDiscriminated union. The type field selects which schema applies.

SetupAction

A setup action that installs a tool before the step’s commands run.
uses
string
required
Action reference to install a tool before running commands.(minLen:1; templateable)
with
map<string,string> | null
Inputs passed to the action, keyed by the action’s declared input names.(templateable)

TerraformTool

Supported IaC tool for terraform:* CI stepsAllowed values:
  • opentofu
  • terraform

TerraformPlanType

Type of Terraform plan to generateAllowed values:
  • apply
  • destroy

TerraformVariableFilePath

Terraform/OpenTofu tfvars file path relative to the step source base pathType: string

TerraformVariablesValue

Terraform variable map value.One of: map<string,TerraformVariable>, string.

ConcurrencyBehavior

Behavior when the concurrency limit is reachedAllowed values:
  • queue
  • cancel-in-progress

QueueOverflowDiscard

Queue overflow discard strategyAllowed values:
  • oldest
  • newest

EnvironmentVariable

Environment variable — can be a plain string, Parameter Store reference, or Secrets Manager referenceOne of: string | null, ParameterStoreEnvVar, SecretsManagerEnvVar.

GitRepoUrl

Full git repository URL including host.Type: string

DisabledBuildConfig

Disabled build configuration. Valid only for module-driven builds.
type
enum
required
Build method — disables module build executionAllowed values: disabled(templateable)

ImageDockerfileBuildConfig

Dockerfile configuration for image builds
type
enum
required
Build method — use a custom DockerfileAllowed values: dockerfile(templateable)
dockerfile
string | null
default:"Dockerfile"
Path to Dockerfile relative to source.base_path(minLen:1; templateable)
context
string | null
default:"."
Docker build context path relative to source.base_path(templateable)
inject_env_variables_in_dockerfile
boolean | null
Whether to inject environment variables as Docker build args Accepts either a boolean literal or a full template token(templateable)
cache_from
CacheFromConfig
Docker layer cache configurationSee: CacheFromConfig(templateable)

ImageNixpacksBuildConfig

Nixpacks configuration for image builds
type
enum
required
Build method — use Nixpacks auto-detectionAllowed values: nixpacks(templateable)
nixpacks_version
string | null
Nixpacks version to use(templateable)
build_path
string | null
Directory to run the Nixpacks build from, relative to the repository root(templateable)
config_file_path
string | null
Path to the Nixpacks configuration file relative to the repository root(templateable)
nix_pkgs
string[] | null
Additional Nix packages to install(templateable)
apt_pkgs
string[] | null
Additional apt packages to install(templateable)
nix_libs
string[] | null
Additional Nix libraries to install(templateable)
install_cmd
string | null
Custom install command(templateable)
build_cmd
string | null
Custom build command(templateable)
start_cmd
string | null
Application start command(templateable)
cache_from
CacheFromConfig
Docker layer cache configurationSee: CacheFromConfig(templateable)

ImageRailpackBuildConfig

Railpack configuration for image builds
type
enum
required
Build method — use Railpack auto-detectionAllowed values: railpack(templateable)
railpack_version
string | null
Railpack version to use(templateable)
install_cmd
string | null
Custom install command(templateable)
build_cmd
string | null
Custom build command(templateable)
start_cmd
string | null
Application start command(templateable)
cache_from
CacheFromConfig
Docker layer cache configurationSee: CacheFromConfig(templateable)

AwsPermissions

IAM policies configuration for runner roles Used by EC2-backed steps to specify additional permissionsOne of: AwsPermissionsAttach, AwsPermissionsReplace.

InfrastructureType

Execution environment typeAllowed values:
  • ec2
  • ec2-spot

InstanceSize

Instance size can be a single string or array of stringsOne of: string, string[].

StorageConfig

Root volume storage configuration
type
enum
Volume typeAllowed values: gp3 | gp2 | io2 | io1(templateable)
size
integer | null
Volume size in GiB(format:int32; templateable)
iops
integer | null
Provisioned IOPS(format:int32; templateable)
throughput
integer | null
Provisioned throughput in MiB/s(format:int32; templateable)

StaticDockerfileBuildConfig

Dockerfile configuration for static builds
type
enum
required
Build method — use a custom DockerfileAllowed values: dockerfile(templateable)
dockerfile
string | null
default:"Dockerfile"
Path to Dockerfile relative to source.base_path(minLen:1; templateable)
context
string | null
default:"."
Docker build context path relative to source.base_path(templateable)
inject_env_variables_in_dockerfile
boolean | null
Whether to inject environment variables as Docker build args Accepts either a boolean literal or a full template token(templateable)
output_directory
string
required
Directory inside the built image containing the static assets to upload This path is resolved relative to source.base_path(minLen:1; templateable)

StaticNixpacksBuildConfig

Nixpacks configuration for static builds
type
enum
required
Build method — use Nixpacks auto-detectionAllowed values: nixpacks(templateable)
nixpacks_version
string | null
Nixpacks version to use(templateable)
build_path
string | null
Directory to run the Nixpacks build from, relative to the repository root(templateable)
config_file_path
string | null
Path to the Nixpacks configuration file relative to the repository root(templateable)
nix_pkgs
string[] | null
Additional Nix packages to install(templateable)
apt_pkgs
string[] | null
Additional apt packages to install(templateable)
nix_libs
string[] | null
Additional Nix libraries to install(templateable)
install_cmd
string | null
Custom install command(templateable)
build_cmd
string | null
Custom build command(templateable)
output_directory
string
required
Directory inside the built image containing the static assets to upload This path is resolved relative to source.base_path(minLen:1; templateable)

StaticRailpackBuildConfig

Railpack configuration for static builds
type
enum
required
Build method — use Railpack auto-detectionAllowed values: railpack(templateable)
railpack_version
string | null
Railpack version to use(templateable)
install_cmd
string | null
Custom install command(templateable)
build_cmd
string | null
Custom build command(templateable)
output_directory
string
required
Directory inside the built image containing the static assets to upload This path is resolved relative to source.base_path(minLen:1; templateable)

TerraformVariable

Terraform variable — can be any JSON value (string, number, boolean, null, array, object), a Parameter Store reference, or a Secrets Manager referenceOne of: ParameterStoreEnvVar, SecretsManagerEnvVar, any | null.

ParameterStoreEnvVar

Environment variable from AWS Parameter Store
from_parameter_store
ParameterStoreReferenceValue
required
Parameter Store referenceSee: ParameterStoreReferenceValue(templateable)

SecretsManagerEnvVar

Environment variable from AWS Secrets Manager
from_secrets_manager
SecretsManagerReferenceValue
required
Secrets Manager referenceSee: SecretsManagerReferenceValue(templateable)

CacheFromConfig

Configuration for Docker layer cache source from ECR
digest
string | null
Specific image digest to use for cache(templateable)
tag
string | null
Specific image tag to use for cache(templateable)

AwsPermissionsAttach

IAM policies to attach alongside step default policies
attach
string[]
required
AWS managed policy ARNs to attach alongside step default policies(templateable)

AwsPermissionsReplace

IAM policies to replace step default policies entirely
replace
string[]
required
AWS managed policy ARNs to use instead of step default policies(templateable)

EbsVolumeType

EBS volume type for the runner root volumeAllowed values:
  • gp3
  • gp2
  • io2
  • io1

ParameterStoreReferenceValue

Parameter Store reference — shorthand string or object with optional version metadataOne of: string, ParameterStoreReference.

SecretsManagerReferenceValue

Secrets Manager reference — shorthand string or object with optional JSON key/version metadataOne of: string, SecretsManagerReference.

ParameterStoreReference

Parameter Store reference with optional version metadata
key
string
required
Parameter Store parameter name or path(templateable)
version
string | null
Parameter version number(templateable)

SecretsManagerReference

Secrets Manager reference with optional JSON key and version metadata
key
string
required
Secret name or ARN in Secrets Manager(templateable)
json_key
string | null
JSON key to extract from a JSON-structured secret(templateable)
version
string | null
Secret version ID or stage(templateable)

Rollback

Steps to execute if the pipeline fails — runs in order after a failure is detectedUses the same types as Steps.

Template expressions

Fields marked templateable accept << expression >> template tokens.
  • Block mode preserves the resolved type:
  • Interpolation mode always produces a string:
Supported operators: +, -, *, /, %, >, <, >=, <=, ==, !=, &&, ||, !.Ternary: << condition ? trueVal : falseVal >>. Default fallback: << input.x || "fallback" >>.Access: array[0], map["key"], map.key. Functions: len(), upper(), lower().Available namespaces: pipeline.input.*, pipeline.run.{id,description}, pipeline.variant.{id,name}, steps.{id}.{output,input}.*, step.input.*, trigger.payload.{branch,commit,ref,repository,event,tag}.