Stages, jobs and job options

A pipeline is a DAG of jobs. Stages group jobs and add default ordering. See Stages and jobs for the guide.

defaults

YAML path: defaults

Defaults are pipeline-wide defaults inherited by every job.

• Unknown keys are rejected.

Key	Type	Required	Description
runs_on	string or list of string | number | boolean		Default runner labels for jobs that do not set runs_on.
timeout	string		Default job timeout. Examples: 30s, 15m, 1h30m, 2d. A duration such as 30s, 15m, 1h30m or 2d, or an expression.
shell	string		Default shell for run steps.
working_directory	string
retry	integer or retry

Stage

YAML path: stages[]

Stage is an ordered grouping of jobs; stages provide default DAG edges.

• Unknown keys are rejected.

Key	Type	Required	Description
name	string
needs	string or list of string | number | boolean		Stages or jobs that must finish first. Omitted means the previous stage; [] removes the implicit edge.
if	string
jobs	list of Job
template	string
with	map

Job

YAML path: jobs[] / stages[].jobs[]

Job is a node of the run DAG, expanded by its matrix into job instances.

• Unknown keys are rejected.

Key	Type	Required	Description
name	string
runs_on	string or list of string | number | boolean		Runner labels used to route the job.
container	string or container
services	map of services.
env	map of string | number | boolean
steps	list of Step
artifacts	list of artifacts[]
cache	list of cache[]
outputs	map of string | number | boolean		Values exported for needs.<job>.outputs.<key>.
timeout	string		Maximum job duration (plan-limited). Examples: 30s, 15m, 1h30m, 2d. A duration such as 30s, 15m, 1h30m or 2d, or an expression.
retry	integer or retry
allow_failure	boolean or string		Do not fail the run when this job fails.
matrix	string or map of list of any
matrix.include	list of object		Extra combinations (or extra variables merged into matching combinations).
matrix.exclude	list of object		Combinations to remove from the expansion.
matrix.fail_fast	boolean or string
matrix.max_parallel	integer		Minimum: 1.
concurrency	string or concurrency
needs	string or list of string | number | boolean		Jobs or stages that must finish first.
if	string		Condition evaluated after needs resolve. Braces are optional. Default success().
environment	string or environment		Binds the job to a deploy environment, making it a deploy job.
permissions	read-all | write-all or object
permissions.contents	none | read | write
permissions.artifacts	none | read | write
permissions.secrets	none | read | write
permissions.deployments	none | read | write
permissions.id_token	none | read | write
template	string
with	map

container

YAML path: container

• Unknown keys are rejected.

Key	Type	Required	Description
image	string	required	OCI image the job’s steps run in.
env	map of string | number | boolean
user	string
pull_policy	always | if-not-present | never
volumes	list of string
options	string or list of string | number | boolean
credentials	container.credentials

container.credentials

YAML path: container.credentials

RegistryAuth holds registry credentials; values are normally secrets.

• Unknown keys are rejected.

Key	Type	Required	Description
username	string
password	string

services.

YAML path: services.<name>

Service is a sidecar container started before the job’s steps.

• Unknown keys are rejected.

Key	Type	Required	Description
image	string	required
env	map of string | number | boolean
ports	string or list of string | number | boolean
command	string or list of string | number | boolean
volumes	list of string
health	services..health		Health check that must pass before the job’s steps start.

services..health

YAML path: services.<name>.health

Health is a service health check.

• Unknown keys are rejected.

Key	Type	Required	Description
cmd	string
interval	string		Examples: 30s, 15m, 1h30m, 2d. A duration such as 30s, 15m, 1h30m or 2d, or an expression.
timeout	string		Examples: 30s, 15m, 1h30m, 2d. A duration such as 30s, 15m, 1h30m or 2d, or an expression.
retries	integer
start_period	string		Examples: 30s, 15m, 1h30m, 2d. A duration such as 30s, 15m, 1h30m or 2d, or an expression.

cache[]

YAML path: cache[]

Cache is a keyed cache restored before and saved after the job’s steps.

• Unknown keys are rejected.

Key	Type	Required	Description
key	string	required	Cache key; usually includes hashFiles(…).
restore_keys	string or list of string | number | boolean		Fallback key prefixes tried in order when key misses.
paths	string or list of string | number | boolean	required

artifacts[]

YAML path: artifacts[]

Artifact uploads files at the end of a job.

• Unknown keys are rejected.

Key	Type	Required	Description
name	string	required
path	string or list of string | number | boolean	required
when	success | failure | always
retention	string		How long the artifact is kept (capped by plan). Examples: 30s, 15m, 1h30m, 2d. A duration such as 30s, 15m, 1h30m or 2d, or an expression.
if_no_files	warn | error | ignore

retry

YAML path: retry

• Unknown keys are rejected.

Key	Type	Required	Description
max	integer	required	Maximum number of retries.
backoff	string		Delay before each retry. Examples: 30s, 15m, 1h30m, 2d. A duration such as 30s, 15m, 1h30m or 2d, or an expression.
when	runner_lost | timeout | failure | any or list of runner_lost | timeout | failure | any		Failure reasons that trigger a retry.

concurrency

YAML path: concurrency

• Unknown keys are rejected.

Key	Type	Required	Description
group	string	required	Runs sharing a group do not run concurrently.
cancel_in_progress	boolean or string		Cancel the older run instead of queueing.

environment

YAML path: environment

• Unknown keys are rejected.

Key	Type	Required	Description
name	string	required
url	string		URL shown in the UI for this deployment.
service	string		The deploy-domain service being deployed.