Legend
StepInfrastructure
Step infrastructure configuration, discriminated bytypeNote: Additional validation via CEL:- every infrastructure type needs exactly one target mode: execution_environment_id, or aws_account_id plus region
- an instance_size list must not mix x86_64 and ARM64 (Graviton) types
- a sandbox with disk_cache: auto needs a git source to name its disk by (a github:runner step names it by its job)
- a sandbox’s cache_paths need disk_cache, and are clean absolute directories outside the guest’s own
type field selects which schema applies.SetupAction
A setup action that installs a tool before the step’s commands run. Resolved against the Flightcontrol actions registry (ravionhq/actions).string
required
Action reference to install a tool before running commands.
Shorthand (“go”, “make”) resolves to
ravionhq/actions/<name>@main,
or a full ref like ravionhq/actions/go@v1.(minLen:1; templateable)map<string,string> | null
Inputs passed to the action, keyed by the action’s declared input names.(templateable)
ExecutionEnvironmentOverrides
Overrides applied on top of the resolved execution environment.An execution environment is a saved network placement. These fields replace individual attributes of whichever environment the step resolved — the one named byexecution_environment_id, the AWS account’s default when none was
named, or the network selected from aws_account_id plus region. Every
attribute that is not overridden keeps the resolved value.Replace semantics, not append: an overridden attribute is the only value
used. Overriding does not require naming an environment.Both the block as a whole and each field inside it are templateable, so a
security group produced by an earlier step can be wired straight in.string | null
Security group ID the runner is launched with, replacing the resolved
execution environment’s security group.(minLen:1; templateable)
string | null
Subnet ID the runner is launched into, replacing the resolved execution
environment’s subnet. It must be in the environment’s VPC, or in the VPC
vpc names.(minLen:1; templateable)string | null
VPC ID the runner runs in, replacing the resolved execution environment’s
VPC. A subnet and a security group belong to one VPC, so a VPC other than
the environment’s is taken only with
subnet and security_group naming
a subnet and a security group in it.(minLen:1; templateable)Ec2SpotStepInfrastructure
Spot EC2 instance infrastructureenum
required
Infrastructure type — a spot EC2 instanceAllowed values:
ec2-spot(templateable)AwsPermissions
IAM permissions for the runner role — “attach” to add managed policies to the step defaults, or “replace” to use the listed managed policies instead of the step defaults. Accepts AWS managed and customer managed policy ARNs. EC2 runners always keep AmazonSSMManagedInstanceCore, CloudWatchAgentServerPolicy, and any inline policies Ravion adds (such as access to referenced secrets).See: AwsPermissions(templateable)
string | null
ID or given ID of a pre-configured execution environment(templateable)
string | null
AWS account reference for automatic network selection.Accepts either the Ravion AWS account database ID (e.g.
awsact_123) or the user-provided givenId configured on the AWS
account. The resolver normalizes the value to the DB id before any
downstream use; the givenId form is an input alias only and is never
persisted as the canonical reference.(templateable)string | null
AWS region for automatic network selection(templateable)
ExecutionEnvironmentOverrides
Overrides for individual attributes of the resolved execution environment.
Valid with or without
execution_environment_id — without one, they apply
on top of the default environment or the auto-selected network.
The whole block and each field inside it accept template tokens.See: ExecutionEnvironmentOverrides(templateable)string | null
AMI ID for the runner instance(templateable)
StorageConfig
string | string[]
required
One EC2 instance type, or a list tried in order when spot capacity is short(templateable)
Ec2StepInfrastructure
On-demand EC2 instance infrastructureenum
required
Infrastructure type — an on-demand EC2 instanceAllowed values:
ec2(templateable)AwsPermissions
IAM permissions for the runner role — “attach” to add managed policies to the step defaults, or “replace” to use the listed managed policies instead of the step defaults. Accepts AWS managed and customer managed policy ARNs. EC2 runners always keep AmazonSSMManagedInstanceCore, CloudWatchAgentServerPolicy, and any inline policies Ravion adds (such as access to referenced secrets).See: AwsPermissions(templateable)
string | null
ID or given ID of a pre-configured execution environment(templateable)
string | null
AWS account reference for automatic network selection.Accepts either the Ravion AWS account database ID (e.g.
awsact_123) or the user-provided givenId configured on the AWS
account. The resolver normalizes the value to the DB id before any
downstream use; the givenId form is an input alias only and is never
persisted as the canonical reference.(templateable)string | null
AWS region for automatic network selection(templateable)
ExecutionEnvironmentOverrides
Overrides for individual attributes of the resolved execution environment.
Valid with or without
execution_environment_id — without one, they apply
on top of the default environment or the auto-selected network.
The whole block and each field inside it accept template tokens.See: ExecutionEnvironmentOverrides(templateable)string | null
AMI ID for the runner instance(templateable)
StorageConfig
string | string[]
required
EC2 instance type — a single type like “t3.large” or an array like [“t3.large”, “t3.xlarge”]; when an array is given the first entry is used(templateable)
SandboxStepInfrastructure
Firecracker microVM infrastructure on the sandbox host pool of the resolved execution environment. With an AWS account and region target, the matching environment is created on first use if needed. A newly created environment has no sandbox pool, so the step fails until a pool is enabled on it.enum
required
Infrastructure type — a Firecracker microVM on the resolved execution environment’s sandbox host poolAllowed values:
sandbox(templateable)AwsPermissions
IAM permissions for the runner role — “attach” to add managed policies to the step defaults, or “replace” to use the listed managed policies instead of the step defaults. Accepts AWS managed and customer managed policy ARNs. EC2 runners always keep AmazonSSMManagedInstanceCore, CloudWatchAgentServerPolicy, and any inline policies Ravion adds (such as access to referenced secrets).See: AwsPermissions(templateable)
string | null
ID or given ID of a pre-configured execution environment(templateable)
string | null
AWS account reference for automatic network selection.Accepts either the Ravion AWS account database ID (e.g.
awsact_123) or the user-provided givenId configured on the AWS
account. The resolver normalizes the value to the DB id before any
downstream use; the givenId form is an input alias only and is never
persisted as the canonical reference.(templateable)string | null
AWS region for automatic network selection(templateable)
integer
required
vCPUs given to the sandbox microVM(format:int32,min:1; templateable)
integer
required
Memory in GiB given to the sandbox microVM(format:int32,min:1; templateable)
integer | null
GiB of host disk the sandbox microVM may write — the restored lineage
overlay plus everything the step builds before it is frozen. A host takes
the sandbox only when it has this much free, and stops it if it writes
more, failing the step with SandboxDiskExceeded, so a step that writes
more than the default must say so.(format:int32,min:1; templateable)
string | null
Whether the sandbox keeps its disk between runs, and which disk.
off
boots the pool’s base image every run and keeps nothing. auto keeps the
step’s own disk, named by its git source and step (a GitHub runner job’s
by its repository, workflow and job), so it needs a git source. Any other
value is a key: every step in the same execution environment that names
the same key shares one disk, across repositories, pipelines and branches.
The last green run to finish publishes it. Include repository or branch
in the key when you want that separation. Explicit keys use the fixed
main head with no branch fallback. Only auto restores from the run’s
branch, falling back to its base and default branches, and publishes to
the run’s branch. Keys are up to 200 lowercase letters, digits, ”.”,
”_” or ”-”.(minLen:1; templateable)string[] | null
Directories to keep with the build caches. A sandbox that keeps its disk
keeps everything on it between runs. A new version of the pool’s base
image moves the disk onto the new image at its next run: the build caches
go with it, and everything else starts again from the new image. A new
major version of the base image starts the build caches again too. Docker’s
images, layers and volumes, the GitHub Actions tool cache and job
workspaces, the checkout and the home directory
/root are always kept.
List another directory here when a step keeps a cache somewhere else,
such as a tool under /opt or /usr/local. Up to 16 absolute
directories, outside /proc, /sys, /dev, /run, /tmp,
/etc/ravion and /var/lib/ravion.(templateable)boolean | null
Whether the step can be stopped partway and started over. Only an
interruptible step can be placed on a spot host, and it is run again on
another host if its host is lost or reclaimed. Leave it off for steps that
change things outside the sandbox and can’t safely be cut off and repeated,
such as database migrations.(templateable)
ExecutionEnvironmentOverrides
Overrides for individual attributes of the resolved execution environment.
A sandbox runs on a host of the environment’s pool, so the host’s network
is the step’s: a step whose overrides name another security group or
subnet runs on a pool host launched into them, which is ended at its idle
timer rather than kept. The whole block and each field inside it accept
template tokens.See: ExecutionEnvironmentOverrides(templateable)
AwsPermissions
IAM policies configuration for runner roles Used by EC2-backed steps to specify additional permissionsOne of: AwsPermissionsAttach, AwsPermissionsReplace.InstanceSize
Instance size can be a single string or array of stringsOne of: string, string[].StorageConfig
Root volume storage configurationenum
Volume typeAllowed values:
gp3 | gp2 | io2 | io1(templateable)integer | null
Volume size in GiB(format:int32; templateable)
integer | null
Provisioned IOPS(format:int32; templateable)
integer | null
Provisioned throughput in MiB/s(format:int32; templateable)
AwsPermissionsAttach
IAM policies to attach alongside step default policiesstring[]
required
IAM managed policy ARNs to attach alongside step default policies — AWS managed policies or customer managed policies in the runner’s AWS account(templateable)
AwsPermissionsReplace
IAM policies to replace step default policies entirelystring[]
required
IAM managed policy ARNs to use instead of step default policies — AWS managed policies or customer managed policies in the runner’s AWS account. Removes every step default policy, including AdministratorAccess on terraform:apply; EC2 runner baseline policies still apply.(templateable)
EbsVolumeType
EBS volume type for the runner root volumeAllowed values:gp3gp2io2io1