Buildkite

Buildkite pipeline.yml files

Type object
File match buildkite.yml buildkite.yaml buildkite.json buildkite.*.yml buildkite.*.yaml buildkite.*.json **/.buildkite/pipeline.yml **/.buildkite/pipeline.yaml **/.buildkite/pipeline.json **/.buildkite/pipeline.*.yml **/.buildkite/pipeline.*.yaml **/.buildkite/pipeline.*.json
Schema URL https://catalog.lintel.tools/schemas/schemastore/buildkite/latest.json
Source https://raw.githubusercontent.com/buildkite/pipeline-schema/main/schema.json

Validate with Lintel

npx @lintel/lintel check
Type: object

Properties

env object

Environment variables for this step

Examples: {"NODE_ENV":"test"}
image string

(Kubernetes stack only) The container image to use for this pipeline or step

Examples: "node:18-alpine", "python:3.11", "ubuntu:22.04"
secrets string[] | object

A list of secret names or a mapping of environment variable names to secret names to be made available to the build or step

priority integer

Priority of all jobs in the pipeline, higher priorities are assigned to agents. When set pipeline-wide, it applies to all steps that do not have their own priority key set.

Examples: -1, 0, 10

Definitions

allowDependencyFailure enum

Whether to proceed with this step and further steps if a step named in the depends_on attribute fails

image string

(Kubernetes stack only) The container image to use for this pipeline or step

Examples:
  • "node:18-alpine"
  • "python:3.11"
  • "ubuntu:22.04"
allowedTeams string | string[]

A list of teams that are permitted to unblock this step, whose values are a list of one or more team slugs or IDs

Examples:
  • "frontend-team"
  • "96176d08-f503-413f-8423-96094953b9e7"
  • [ "frontend-team", "backend-team", "96176d08-f503-413f-8423-96094953b9e7" ]
agents agentsObject | agentsList
agentsObject object

Query rules to target specific agents

Examples:
  • { "queue": "deploy" }
  • { "ruby": "2*" }
agentsList string[]

Query rules to target specific agents in k=v format

Examples:
  • "queue=default"
  • "xcode=true"
automaticRetry object
exit_status string | integer | integer[]

The exit status number that will cause this job to retry

limit integer

The number of times this job can be retried

min=0max=10
signal string

The exit signal, if any, that may be retried

Examples: "*", "none", "SIGKILL", "term"
signal_reason string

The exit signal reason, if any, that may be retried

Values: "*" "none" "agent_incompatible" "agent_refused" "agent_stop" "cancel" "process_run_error" "signature_rejected" "stack_error"
branches string | string[]

Which branches will include this step in their builds

Examples:
  • "master"
  • [ "feature/*", "chore/*" ]
cache string | string[] | object

The paths for the caches to be used in the step

Examples:
  • "dist/"
  • [ ".build/*", "assets/*" ]
  • { "name": "cool-cache", "size": "20g", "paths": [ "/path/one", "/path/two" ] }
cancelOnBuildFailing enum

Whether to cancel the job as soon as the build is marked as failing

dependsOnList string | object[]
dependsOn null | string | dependsOnList

The step keys for a step to depend on

env object

Environment variables for this step

Examples:
  • { "NODE_ENV": "test" }
if string

A boolean expression that omits the step when false

Examples:
  • "build.message != 'skip me'"
  • "build.branch == 'master'"
key string

A unique identifier for a step, must not resemble a UUID

Examples:
  • "deploy-staging"
  • "test-integration"
label string

The label that will be displayed in the pipeline visualisation in Buildkite. Supports emoji.

Examples:
  • ":docker: Build"
notifySimple string
notifyEmail object
email string
if string

A boolean expression that omits the step when false

Examples: "build.message != 'skip me'", "build.branch == 'master'"
notifyBasecamp object
basecamp_campfire string
if string

A boolean expression that omits the step when false

Examples: "build.message != 'skip me'", "build.branch == 'master'"
notifySlackObject object
channels string[]
message string
notifySlack object
slack string | notifySlackObject
if string

A boolean expression that omits the step when false

Examples: "build.message != 'skip me'", "build.branch == 'master'"
notifyWebhook object
webhook string
if string

A boolean expression that omits the step when false

Examples: "build.message != 'skip me'", "build.branch == 'master'"
notifyPagerduty object
pagerduty_change_event string
if string

A boolean expression that omits the step when false

Examples: "build.message != 'skip me'", "build.branch == 'master'"
notifyGithubCommitStatus object
github_commit_status object
1 nested properties
context string

GitHub commit status name

if string

A boolean expression that omits the step when false

Examples: "build.message != 'skip me'", "build.branch == 'master'"
notifyGithubCheck object
github_check object
buildNotify notifySimple | notifyEmail | notifyBasecamp | notifySlack | notifyWebhook | notifyPagerduty | notifyGithubCommitStatus | notifyGithubCheck[]

Array of notification options for this step

textField object
key string required

The meta-data key that stores the field's input

Examples: "release-name"
pattern=^[a-zA-Z0-9-_]+$
text string

The text input name

Examples: "Release Name"
hint string

The explanatory text that is shown after the label

Examples: "What’s the code name for this release? :name_badge:"
format string

The format must be a regular expression implicitly anchored to the beginning and end of the input and is functionally equivalent to the HTML5 pattern attribute.

Examples: "[0-9a-f]+"
format=regex
required enum

Whether the field is required for form submission

Default: true
Values: true false "true" "false"
default string

The value that is pre-filled in the text field

Examples: "Flying Dolphin"
selectFieldOption object
label string required

The text displayed on the select list item

Examples: "Stable"
value string required

The value to be stored as meta-data

Examples: "stable"
hint string

The text displayed directly under the select field’s label

Examples: "Which release stream does this belong in? :fork:"
required enum

Whether the field is required for form submission

Default: true
Values: true false "true" "false"
selectField object
key string required

The meta-data key that stores the field's input

Examples: "release-stream"
pattern=^[a-zA-Z0-9-_]+$
options selectFieldOption[] required
minItems=1
select string

The text input name

Examples: "Release Stream"
default string | string[]

The value of the option(s) that will be pre-selected in the dropdown

Examples: "beta", ["alpha","beta"]
hint string

The explanatory text that is shown after the label

Examples: "What’s the code name for this release? :name_badge:"
multiple enum

Whether more than one option may be selected

Default: false
Values: true false "true" "false"
required enum

Whether the field is required for form submission

Default: true
Values: true false "true" "false"
fields textField | selectField[]

A list of input fields required to be filled out before unblocking the step

ifChanged string | string[] | object

Agent-applied attribute: A glob pattern that omits the step from a build if it does not match any files changed in the build. Can be a single pattern, list of patterns, or an object with include/exclude attributes.

matrixElement string | integer | boolean
prompt string

The instructional message displayed in the dialog box when the unblock step is activated

Examples:
  • "Release to production?"
skip boolean | string

Whether this step should be skipped. Passing a string provides a reason for skipping this command

Examples:
  • true
  • false
  • "My reason"
secrets string[] | object

A list of secret names or a mapping of environment variable names to secret names to be made available to the build or step

softFailObject object
exit_status string | integer

The exit status number that will cause this job to soft-fail

softFailList softFailObject[]
softFail enum | softFailList

The conditions for marking the step as a soft-fail.

blockStep object
allow_dependency_failure enum

Whether to proceed with this step and further steps if a step named in the depends_on attribute fails

Default: false
Values: true false "true" "false"
block string

The label of the block step

blocked_state string

The state that the build is set to when the build is blocked by this block step

Default: "passed"
Values: "passed" "failed" "running"
branches string | string[]

Which branches will include this step in their builds

Examples: "master", ["feature/*","chore/*"]
depends_on null | string | dependsOnList

The step keys for a step to depend on

fields textField | selectField[]

A list of input fields required to be filled out before unblocking the step

if string

A boolean expression that omits the step when false

Examples: "build.message != 'skip me'", "build.branch == 'master'"
key string

A unique identifier for a step, must not resemble a UUID

Examples: "deploy-staging", "test-integration"
maxLength=100pattern=^[a-zA-Z0-9_\-:${}.,]+$
identifier key
id key
label string

The label of the block step

name string

The label of the block step

prompt string

The instructional message displayed in the dialog box when the unblock step is activated

Examples: "Release to production?"
allowed_teams string | string[]

A list of teams that are permitted to unblock this step, whose values are a list of one or more team slugs or IDs

Examples: "frontend-team", "96176d08-f503-413f-8423-96094953b9e7", ["frontend-team","backend-team","96176d08-f503-413f-8423-96094953b9e7"]
type string
Values: "block"
nestedBlockStep object
block object
15 nested properties
allow_dependency_failure enum

Whether to proceed with this step and further steps if a step named in the depends_on attribute fails

Default: false
Values: true false "true" "false"
block string

The label of the block step

blocked_state string

The state that the build is set to when the build is blocked by this block step

Default: "passed"
Values: "passed" "failed" "running"
branches string | string[]

Which branches will include this step in their builds

Examples: "master", ["feature/*","chore/*"]
depends_on null | string | dependsOnList

The step keys for a step to depend on

fields textField | selectField[]

A list of input fields required to be filled out before unblocking the step

if string

A boolean expression that omits the step when false

Examples: "build.message != 'skip me'", "build.branch == 'master'"
key string

A unique identifier for a step, must not resemble a UUID

Examples: "deploy-staging", "test-integration"
maxLength=100pattern=^[a-zA-Z0-9_\-:${}.,]+$
identifier key
id key
label string

The label of the block step

name string

The label of the block step

prompt string

The instructional message displayed in the dialog box when the unblock step is activated

Examples: "Release to production?"
allowed_teams string | string[]

A list of teams that are permitted to unblock this step, whose values are a list of one or more team slugs or IDs

Examples: "frontend-team", "96176d08-f503-413f-8423-96094953b9e7", ["frontend-team","backend-team","96176d08-f503-413f-8423-96094953b9e7"]
type string
Values: "block"
stringBlockStep string

Pauses the execution of a build and waits on a user to unblock it

inputStep object
allow_dependency_failure enum

Whether to proceed with this step and further steps if a step named in the depends_on attribute fails

Default: false
Values: true false "true" "false"
input string

The label of the input step

branches string | string[]

Which branches will include this step in their builds

Examples: "master", ["feature/*","chore/*"]
depends_on null | string | dependsOnList

The step keys for a step to depend on

fields textField | selectField[]

A list of input fields required to be filled out before unblocking the step

blocked_state string

The state that the build is set to when the build is blocked by this input step

Default: "passed"
Values: "passed" "failed" "running"
if string

A boolean expression that omits the step when false

Examples: "build.message != 'skip me'", "build.branch == 'master'"
key string

A unique identifier for a step, must not resemble a UUID

Examples: "deploy-staging", "test-integration"
maxLength=100pattern=^[a-zA-Z0-9_\-:${}.,]+$
identifier key
id key
label string

The label of the input step

name string

The label of the input step

prompt string

The instructional message displayed in the dialog box when the unblock step is activated

Examples: "Release to production?"
allowed_teams string | string[]

A list of teams that are permitted to unblock this step, whose values are a list of one or more team slugs or IDs

Examples: "frontend-team", "96176d08-f503-413f-8423-96094953b9e7", ["frontend-team","backend-team","96176d08-f503-413f-8423-96094953b9e7"]
type string
Values: "input"
nestedInputStep object
input object
15 nested properties
allow_dependency_failure enum

Whether to proceed with this step and further steps if a step named in the depends_on attribute fails

Default: false
Values: true false "true" "false"
input string

The label of the input step

branches string | string[]

Which branches will include this step in their builds

Examples: "master", ["feature/*","chore/*"]
depends_on null | string | dependsOnList

The step keys for a step to depend on

fields textField | selectField[]

A list of input fields required to be filled out before unblocking the step

blocked_state string

The state that the build is set to when the build is blocked by this input step

Default: "passed"
Values: "passed" "failed" "running"
if string

A boolean expression that omits the step when false

Examples: "build.message != 'skip me'", "build.branch == 'master'"
key string

A unique identifier for a step, must not resemble a UUID

Examples: "deploy-staging", "test-integration"
maxLength=100pattern=^[a-zA-Z0-9_\-:${}.,]+$
identifier key
id key
label string

The label of the input step

name string

The label of the input step

prompt string

The instructional message displayed in the dialog box when the unblock step is activated

Examples: "Release to production?"
allowed_teams string | string[]

A list of teams that are permitted to unblock this step, whose values are a list of one or more team slugs or IDs

Examples: "frontend-team", "96176d08-f503-413f-8423-96094953b9e7", ["frontend-team","backend-team","96176d08-f503-413f-8423-96094953b9e7"]
type string
Values: "input"
stringInputStep string

Pauses the execution of a build and waits on a user to unblock it

matrixElementList matrixElement[]

List of elements for single-dimension Build Matrix

Examples:
  • [ "linux", "freebsd" ]
matrixSetup matrixElementList | object
matrixAdjustmentsWithObject Record<string, string>

Specification of a new or existing Build Matrix combination

Examples:
  • { "os": "linux", "arch": "arm64" }
matrixAdjustments object

An adjustment to a Build Matrix

with matrixElementList | matrixAdjustmentsWithObject required
skip boolean | string

Whether this step should be skipped. Passing a string provides a reason for skipping this command

Examples: true, false, "My reason"
soft_fail enum | softFailList

The conditions for marking the step as a soft-fail.

matrixObject object

Configuration for multi-dimension Build Matrix

setup matrixElementList | object required
adjustments matrixAdjustments[]

List of Build Matrix adjustments

matrix matrixElementList | matrixObject
commandStepCommand string[] | string

The commands to run on the agent

commandStepNotify notifySimple | notifyBasecamp | notifySlack | notifyGithubCommitStatus | notifyGithubCheck[]

Array of notification options for this step

pluginsList string | object[]

Array of plugins for this step

pluginsObject object

A map of plugins for this step. Deprecated: please use the array syntax.

plugins pluginsList | pluginsObject
automaticRetryList automaticRetry[]
commandStepAutomaticRetry enum | automaticRetry | automaticRetryList

Whether to allow a job to retry automatically. If set to true, the retry conditions are set to the default value.

commandStepManualRetryObject object
allowed enum

Whether or not this job can be retried manually

Default: true
Values: true false "true" "false"
permit_on_passed enum

Whether or not this job can be retried after it has passed

Default: true
Values: true false "true" "false"
reason string

A string that will be displayed in a tooltip on the Retry button in Buildkite. This will only be displayed if the allowed attribute is set to false.

Examples: "No retries allowed on deploy steps"
commandStepManualRetry enum | commandStepManualRetryObject

Whether to allow a job to be retried manually

commandStep object
agents agentsObject | agentsList
allow_dependency_failure enum

Whether to proceed with this step and further steps if a step named in the depends_on attribute fails

Default: false
Values: true false "true" "false"
artifact_paths string | string[]

The glob path/s of artifacts to upload once this step has finished running

Examples: ["screenshots/*"], ["dist/myapp.zip","dist/myapp.tgz"]
branches string | string[]

Which branches will include this step in their builds

Examples: "master", ["feature/*","chore/*"]
cache string | string[] | object

The paths for the caches to be used in the step

Examples: "dist/", [".build/*","assets/*"], {"name":"cool-cache","size":"20g","paths":["/path/one","/path/two"]}
cancel_on_build_failing enum

Whether to cancel the job as soon as the build is marked as failing

Default: false
Values: true false "true" "false"
command string[] | string

The commands to run on the agent

commands string[] | string

The commands to run on the agent

concurrency integer

The maximum number of jobs created from this step that are allowed to run at the same time. If you use this attribute, you must also define concurrency_group.

Examples: 1
concurrency_group string

A unique name for the concurrency group that you are creating with the concurrency attribute

Examples: "my-pipeline/deploy"
concurrency_method string

Control command order, allowed values are 'ordered' (default) and 'eager'. If you use this attribute, you must also define concurrency_group and concurrency.

Values: "ordered" "eager"
Examples: "ordered"
depends_on null | string | dependsOnList

The step keys for a step to depend on

env object

Environment variables for this step

Examples: {"NODE_ENV":"test"}
if string

A boolean expression that omits the step when false

Examples: "build.message != 'skip me'", "build.branch == 'master'"
if_changed string | string[] | object

Agent-applied attribute: A glob pattern that omits the step from a build if it does not match any files changed in the build. Can be a single pattern, list of patterns, or an object with include/exclude attributes.

key string

A unique identifier for a step, must not resemble a UUID

Examples: "deploy-staging", "test-integration"
maxLength=100pattern=^[a-zA-Z0-9_\-:${}.,]+$
identifier key
id key
image string

(Kubernetes stack only) The container image to use for this pipeline or step

Examples: "node:18-alpine", "python:3.11", "ubuntu:22.04"
label string

The label that will be displayed in the pipeline visualisation in Buildkite. Supports emoji.

Examples: ":docker: Build"
signature object

The signature of the command step, generally injected by agents at pipeline upload

3 nested properties
algorithm string

The algorithm used to generate the signature

Examples: "HS512", "EdDSA", "PS256"
value string

The signature value, a JWS compact signature with a detached body

signed_fields string[]

The fields that were signed to form the signature value

Examples: ["command","matrix","plugins","env::SOME_ENV_VAR"]
matrix matrixElementList | matrixObject
name label
notify notifySimple | notifyBasecamp | notifySlack | notifyGithubCommitStatus | notifyGithubCheck[]

Array of notification options for this step

parallelism integer

The number of parallel jobs that will be created based on this step

Examples: 42
plugins pluginsList | pluginsObject
soft_fail enum | softFailList

The conditions for marking the step as a soft-fail.

retry object

The conditions for retrying this step.

2 nested properties
automatic enum | automaticRetry | automaticRetryList

Whether to allow a job to retry automatically. If set to true, the retry conditions are set to the default value.

Default:
[
  {
    "exit_status": "*",
    "limit": 2
  }
]
manual enum | commandStepManualRetryObject

Whether to allow a job to be retried manually

Default: true
skip boolean | string

Whether this step should be skipped. Passing a string provides a reason for skipping this command

Examples: true, false, "My reason"
timeout_in_minutes integer

The number of minutes to time out a job

Examples: 60
min=1
type string
Values: "script" "command" "commands"
priority integer

Priority of all jobs in the pipeline, higher priorities are assigned to agents. When set pipeline-wide, it applies to all steps that do not have their own priority key set.

Examples: -1, 0, 10
secrets string[] | object

A list of secret names or a mapping of environment variable names to secret names to be made available to the build or step

nestedCommandStep object
command object
33 nested properties
agents agentsObject | agentsList
allow_dependency_failure enum

Whether to proceed with this step and further steps if a step named in the depends_on attribute fails

Default: false
Values: true false "true" "false"
artifact_paths string | string[]

The glob path/s of artifacts to upload once this step has finished running

Examples: ["screenshots/*"], ["dist/myapp.zip","dist/myapp.tgz"]
branches string | string[]

Which branches will include this step in their builds

Examples: "master", ["feature/*","chore/*"]
cache string | string[] | object

The paths for the caches to be used in the step

Examples: "dist/", [".build/*","assets/*"], {"name":"cool-cache","size":"20g","paths":["/path/one","/path/two"]}
cancel_on_build_failing enum

Whether to cancel the job as soon as the build is marked as failing

Default: false
Values: true false "true" "false"
command string[] | string

The commands to run on the agent

commands string[] | string

The commands to run on the agent

concurrency integer

The maximum number of jobs created from this step that are allowed to run at the same time. If you use this attribute, you must also define concurrency_group.

Examples: 1
concurrency_group string

A unique name for the concurrency group that you are creating with the concurrency attribute

Examples: "my-pipeline/deploy"
concurrency_method string

Control command order, allowed values are 'ordered' (default) and 'eager'. If you use this attribute, you must also define concurrency_group and concurrency.

Values: "ordered" "eager"
Examples: "ordered"
depends_on null | string | dependsOnList

The step keys for a step to depend on

env object

Environment variables for this step

Examples: {"NODE_ENV":"test"}
if string

A boolean expression that omits the step when false

Examples: "build.message != 'skip me'", "build.branch == 'master'"
if_changed string | string[] | object

Agent-applied attribute: A glob pattern that omits the step from a build if it does not match any files changed in the build. Can be a single pattern, list of patterns, or an object with include/exclude attributes.

key string

A unique identifier for a step, must not resemble a UUID

Examples: "deploy-staging", "test-integration"
maxLength=100pattern=^[a-zA-Z0-9_\-:${}.,]+$
identifier key
id key
image string

(Kubernetes stack only) The container image to use for this pipeline or step

Examples: "node:18-alpine", "python:3.11", "ubuntu:22.04"
label string

The label that will be displayed in the pipeline visualisation in Buildkite. Supports emoji.

Examples: ":docker: Build"
signature object

The signature of the command step, generally injected by agents at pipeline upload

3 nested properties
algorithm string

The algorithm used to generate the signature

Examples: "HS512", "EdDSA", "PS256"
value string

The signature value, a JWS compact signature with a detached body

signed_fields string[]

The fields that were signed to form the signature value

Examples: ["command","matrix","plugins","env::SOME_ENV_VAR"]
matrix matrixElementList | matrixObject
name label
notify notifySimple | notifyBasecamp | notifySlack | notifyGithubCommitStatus | notifyGithubCheck[]

Array of notification options for this step

parallelism integer

The number of parallel jobs that will be created based on this step

Examples: 42
plugins pluginsList | pluginsObject
soft_fail enum | softFailList

The conditions for marking the step as a soft-fail.

retry object

The conditions for retrying this step.

2 nested properties
automatic enum | automaticRetry | automaticRetryList

Whether to allow a job to retry automatically. If set to true, the retry conditions are set to the default value.

Default:
[
  {
    "exit_status": "*",
    "limit": 2
  }
]
manual enum | commandStepManualRetryObject

Whether to allow a job to be retried manually

Default: true
skip boolean | string

Whether this step should be skipped. Passing a string provides a reason for skipping this command

Examples: true, false, "My reason"
timeout_in_minutes integer

The number of minutes to time out a job

Examples: 60
min=1
type string
Values: "script" "command" "commands"
priority integer

Priority of all jobs in the pipeline, higher priorities are assigned to agents. When set pipeline-wide, it applies to all steps that do not have their own priority key set.

Examples: -1, 0, 10
secrets string[] | object

A list of secret names or a mapping of environment variable names to secret names to be made available to the build or step

commands object
33 nested properties
agents agentsObject | agentsList
allow_dependency_failure enum

Whether to proceed with this step and further steps if a step named in the depends_on attribute fails

Default: false
Values: true false "true" "false"
artifact_paths string | string[]

The glob path/s of artifacts to upload once this step has finished running

Examples: ["screenshots/*"], ["dist/myapp.zip","dist/myapp.tgz"]
branches string | string[]

Which branches will include this step in their builds

Examples: "master", ["feature/*","chore/*"]
cache string | string[] | object

The paths for the caches to be used in the step

Examples: "dist/", [".build/*","assets/*"], {"name":"cool-cache","size":"20g","paths":["/path/one","/path/two"]}
cancel_on_build_failing enum

Whether to cancel the job as soon as the build is marked as failing

Default: false
Values: true false "true" "false"
command string[] | string

The commands to run on the agent

commands string[] | string

The commands to run on the agent

concurrency integer

The maximum number of jobs created from this step that are allowed to run at the same time. If you use this attribute, you must also define concurrency_group.

Examples: 1
concurrency_group string

A unique name for the concurrency group that you are creating with the concurrency attribute

Examples: "my-pipeline/deploy"
concurrency_method string

Control command order, allowed values are 'ordered' (default) and 'eager'. If you use this attribute, you must also define concurrency_group and concurrency.

Values: "ordered" "eager"
Examples: "ordered"
depends_on null | string | dependsOnList

The step keys for a step to depend on

env object

Environment variables for this step

Examples: {"NODE_ENV":"test"}
if string

A boolean expression that omits the step when false

Examples: "build.message != 'skip me'", "build.branch == 'master'"
if_changed string | string[] | object

Agent-applied attribute: A glob pattern that omits the step from a build if it does not match any files changed in the build. Can be a single pattern, list of patterns, or an object with include/exclude attributes.

key string

A unique identifier for a step, must not resemble a UUID

Examples: "deploy-staging", "test-integration"
maxLength=100pattern=^[a-zA-Z0-9_\-:${}.,]+$
identifier key
id key
image string

(Kubernetes stack only) The container image to use for this pipeline or step

Examples: "node:18-alpine", "python:3.11", "ubuntu:22.04"
label string

The label that will be displayed in the pipeline visualisation in Buildkite. Supports emoji.

Examples: ":docker: Build"
signature object

The signature of the command step, generally injected by agents at pipeline upload

3 nested properties
algorithm string

The algorithm used to generate the signature

Examples: "HS512", "EdDSA", "PS256"
value string

The signature value, a JWS compact signature with a detached body

signed_fields string[]

The fields that were signed to form the signature value

Examples: ["command","matrix","plugins","env::SOME_ENV_VAR"]
matrix matrixElementList | matrixObject
name label
notify notifySimple | notifyBasecamp | notifySlack | notifyGithubCommitStatus | notifyGithubCheck[]

Array of notification options for this step

parallelism integer

The number of parallel jobs that will be created based on this step

Examples: 42
plugins pluginsList | pluginsObject
soft_fail enum | softFailList

The conditions for marking the step as a soft-fail.

retry object

The conditions for retrying this step.

2 nested properties
automatic enum | automaticRetry | automaticRetryList

Whether to allow a job to retry automatically. If set to true, the retry conditions are set to the default value.

Default:
[
  {
    "exit_status": "*",
    "limit": 2
  }
]
manual enum | commandStepManualRetryObject

Whether to allow a job to be retried manually

Default: true
skip boolean | string

Whether this step should be skipped. Passing a string provides a reason for skipping this command

Examples: true, false, "My reason"
timeout_in_minutes integer

The number of minutes to time out a job

Examples: 60
min=1
type string
Values: "script" "command" "commands"
priority integer

Priority of all jobs in the pipeline, higher priorities are assigned to agents. When set pipeline-wide, it applies to all steps that do not have their own priority key set.

Examples: -1, 0, 10
secrets string[] | object

A list of secret names or a mapping of environment variable names to secret names to be made available to the build or step

script object
33 nested properties
agents agentsObject | agentsList
allow_dependency_failure enum

Whether to proceed with this step and further steps if a step named in the depends_on attribute fails

Default: false
Values: true false "true" "false"
artifact_paths string | string[]

The glob path/s of artifacts to upload once this step has finished running

Examples: ["screenshots/*"], ["dist/myapp.zip","dist/myapp.tgz"]
branches string | string[]

Which branches will include this step in their builds

Examples: "master", ["feature/*","chore/*"]
cache string | string[] | object

The paths for the caches to be used in the step

Examples: "dist/", [".build/*","assets/*"], {"name":"cool-cache","size":"20g","paths":["/path/one","/path/two"]}
cancel_on_build_failing enum

Whether to cancel the job as soon as the build is marked as failing

Default: false
Values: true false "true" "false"
command string[] | string

The commands to run on the agent

commands string[] | string

The commands to run on the agent

concurrency integer

The maximum number of jobs created from this step that are allowed to run at the same time. If you use this attribute, you must also define concurrency_group.

Examples: 1
concurrency_group string

A unique name for the concurrency group that you are creating with the concurrency attribute

Examples: "my-pipeline/deploy"
concurrency_method string

Control command order, allowed values are 'ordered' (default) and 'eager'. If you use this attribute, you must also define concurrency_group and concurrency.

Values: "ordered" "eager"
Examples: "ordered"
depends_on null | string | dependsOnList

The step keys for a step to depend on

env object

Environment variables for this step

Examples: {"NODE_ENV":"test"}
if string

A boolean expression that omits the step when false

Examples: "build.message != 'skip me'", "build.branch == 'master'"
if_changed string | string[] | object

Agent-applied attribute: A glob pattern that omits the step from a build if it does not match any files changed in the build. Can be a single pattern, list of patterns, or an object with include/exclude attributes.

key string

A unique identifier for a step, must not resemble a UUID

Examples: "deploy-staging", "test-integration"
maxLength=100pattern=^[a-zA-Z0-9_\-:${}.,]+$
identifier key
id key
image string

(Kubernetes stack only) The container image to use for this pipeline or step

Examples: "node:18-alpine", "python:3.11", "ubuntu:22.04"
label string

The label that will be displayed in the pipeline visualisation in Buildkite. Supports emoji.

Examples: ":docker: Build"
signature object

The signature of the command step, generally injected by agents at pipeline upload

3 nested properties
algorithm string

The algorithm used to generate the signature

Examples: "HS512", "EdDSA", "PS256"
value string

The signature value, a JWS compact signature with a detached body

signed_fields string[]

The fields that were signed to form the signature value

Examples: ["command","matrix","plugins","env::SOME_ENV_VAR"]
matrix matrixElementList | matrixObject
name label
notify notifySimple | notifyBasecamp | notifySlack | notifyGithubCommitStatus | notifyGithubCheck[]

Array of notification options for this step

parallelism integer

The number of parallel jobs that will be created based on this step

Examples: 42
plugins pluginsList | pluginsObject
soft_fail enum | softFailList

The conditions for marking the step as a soft-fail.

retry object

The conditions for retrying this step.

2 nested properties
automatic enum | automaticRetry | automaticRetryList

Whether to allow a job to retry automatically. If set to true, the retry conditions are set to the default value.

Default:
[
  {
    "exit_status": "*",
    "limit": 2
  }
]
manual enum | commandStepManualRetryObject

Whether to allow a job to be retried manually

Default: true
skip boolean | string

Whether this step should be skipped. Passing a string provides a reason for skipping this command

Examples: true, false, "My reason"
timeout_in_minutes integer

The number of minutes to time out a job

Examples: 60
min=1
type string
Values: "script" "command" "commands"
priority integer

Priority of all jobs in the pipeline, higher priorities are assigned to agents. When set pipeline-wide, it applies to all steps that do not have their own priority key set.

Examples: -1, 0, 10
secrets string[] | object

A list of secret names or a mapping of environment variable names to secret names to be made available to the build or step

stringWaitStep string

Waits for previous steps to pass before continuing

waitStep object
allow_dependency_failure enum

Whether to proceed with this step and further steps if a step named in the depends_on attribute fails

Default: false
Values: true false "true" "false"
branches string | string[]

Which branches will include this step in their builds

Examples: "master", ["feature/*","chore/*"]
continue_on_failure enum

Continue to the next steps, even if the previous group of steps fail

Default: false
Values: true false "true" "false"
depends_on null | string | dependsOnList

The step keys for a step to depend on

if string

A boolean expression that omits the step when false

Examples: "build.message != 'skip me'", "build.branch == 'master'"
key string

A unique identifier for a step, must not resemble a UUID

Examples: "deploy-staging", "test-integration"
maxLength=100pattern=^[a-zA-Z0-9_\-:${}.,]+$
label string | null

Waits for previous steps to pass before continuing

name string | null

Waits for previous steps to pass before continuing

identifier key
id key
type string
Values: "wait" "waiter"
wait string | null

Waits for previous steps to pass before continuing

nestedWaitStep object
wait object
12 nested properties
allow_dependency_failure enum

Whether to proceed with this step and further steps if a step named in the depends_on attribute fails

Default: false
Values: true false "true" "false"
branches string | string[]

Which branches will include this step in their builds

Examples: "master", ["feature/*","chore/*"]
continue_on_failure enum

Continue to the next steps, even if the previous group of steps fail

Default: false
Values: true false "true" "false"
depends_on null | string | dependsOnList

The step keys for a step to depend on

if string

A boolean expression that omits the step when false

Examples: "build.message != 'skip me'", "build.branch == 'master'"
key string

A unique identifier for a step, must not resemble a UUID

Examples: "deploy-staging", "test-integration"
maxLength=100pattern=^[a-zA-Z0-9_\-:${}.,]+$
label string | null

Waits for previous steps to pass before continuing

name string | null

Waits for previous steps to pass before continuing

identifier key
id key
type string
Values: "wait" "waiter"
wait string | null

Waits for previous steps to pass before continuing

waiter object
12 nested properties
allow_dependency_failure enum

Whether to proceed with this step and further steps if a step named in the depends_on attribute fails

Default: false
Values: true false "true" "false"
branches string | string[]

Which branches will include this step in their builds

Examples: "master", ["feature/*","chore/*"]
continue_on_failure enum

Continue to the next steps, even if the previous group of steps fail

Default: false
Values: true false "true" "false"
depends_on null | string | dependsOnList

The step keys for a step to depend on

if string

A boolean expression that omits the step when false

Examples: "build.message != 'skip me'", "build.branch == 'master'"
key string

A unique identifier for a step, must not resemble a UUID

Examples: "deploy-staging", "test-integration"
maxLength=100pattern=^[a-zA-Z0-9_\-:${}.,]+$
label string | null

Waits for previous steps to pass before continuing

name string | null

Waits for previous steps to pass before continuing

identifier key
id key
type string
Values: "wait" "waiter"
wait string | null

Waits for previous steps to pass before continuing

triggerStep object
trigger string required

The slug of the pipeline to create a build

allow_dependency_failure enum

Whether to proceed with this step and further steps if a step named in the depends_on attribute fails

Default: false
Values: true false "true" "false"
async enum

Whether to continue the build without waiting for the triggered step to complete

Default: false
Values: true false "true" "false"
branches string | string[]

Which branches will include this step in their builds

Examples: "master", ["feature/*","chore/*"]
build object

Properties of the build that will be created when the step is triggered

5 nested properties
branch string

The branch for the build

Default: "master"
Examples: "master", "feature/xyz"
commit string

The commit hash for the build

Default: "HEAD"
Examples: "HEAD", "b5fb108"
env object

Environment variables for this step

Examples: {"NODE_ENV":"test"}
message string

The message for the build (supports emoji)

Default: "The label of the trigger step"
Examples: "Deployment 123 :rocket:"
meta_data object

Meta-data for the build

Examples: {"server":"i-b244e37160c"}
depends_on null | string | dependsOnList

The step keys for a step to depend on

if string

A boolean expression that omits the step when false

Examples: "build.message != 'skip me'", "build.branch == 'master'"
if_changed string | string[] | object

Agent-applied attribute: A glob pattern that omits the step from a build if it does not match any files changed in the build. Can be a single pattern, list of patterns, or an object with include/exclude attributes.

key string

A unique identifier for a step, must not resemble a UUID

Examples: "deploy-staging", "test-integration"
maxLength=100pattern=^[a-zA-Z0-9_\-:${}.,]+$
identifier key
id key
label string

The label that will be displayed in the pipeline visualisation in Buildkite. Supports emoji.

Examples: ":docker: Build"
name label
type string
Values: "trigger"
skip boolean | string

Whether this step should be skipped. Passing a string provides a reason for skipping this command

Examples: true, false, "My reason"
soft_fail enum | softFailList

The conditions for marking the step as a soft-fail.

nestedTriggerStep object
trigger object
16 nested properties
trigger string required

The slug of the pipeline to create a build

allow_dependency_failure enum

Whether to proceed with this step and further steps if a step named in the depends_on attribute fails

Default: false
Values: true false "true" "false"
async enum

Whether to continue the build without waiting for the triggered step to complete

Default: false
Values: true false "true" "false"
branches string | string[]

Which branches will include this step in their builds

Examples: "master", ["feature/*","chore/*"]
build object

Properties of the build that will be created when the step is triggered

5 nested properties
branch string

The branch for the build

Default: "master"
Examples: "master", "feature/xyz"
commit string

The commit hash for the build

Default: "HEAD"
Examples: "HEAD", "b5fb108"
env object

Environment variables for this step

Examples: {"NODE_ENV":"test"}
message string

The message for the build (supports emoji)

Default: "The label of the trigger step"
Examples: "Deployment 123 :rocket:"
meta_data object

Meta-data for the build

Examples: {"server":"i-b244e37160c"}
depends_on null | string | dependsOnList

The step keys for a step to depend on

if string

A boolean expression that omits the step when false

Examples: "build.message != 'skip me'", "build.branch == 'master'"
if_changed string | string[] | object

Agent-applied attribute: A glob pattern that omits the step from a build if it does not match any files changed in the build. Can be a single pattern, list of patterns, or an object with include/exclude attributes.

key string

A unique identifier for a step, must not resemble a UUID

Examples: "deploy-staging", "test-integration"
maxLength=100pattern=^[a-zA-Z0-9_\-:${}.,]+$
identifier key
id key
label string

The label that will be displayed in the pipeline visualisation in Buildkite. Supports emoji.

Examples: ":docker: Build"
name label
type string
Values: "trigger"
skip boolean | string

Whether this step should be skipped. Passing a string provides a reason for skipping this command

Examples: true, false, "My reason"
soft_fail enum | softFailList

The conditions for marking the step as a soft-fail.

groupSteps blockStep | nestedBlockStep | stringBlockStep | inputStep | nestedInputStep | stringInputStep | commandStep | nestedCommandStep | waitStep | nestedWaitStep | stringWaitStep | triggerStep | nestedTriggerStep[]

A list of steps

groupStep object
group string | null required

The name to give to this group of steps

Examples: "Tests"
steps blockStep | nestedBlockStep | stringBlockStep | inputStep | nestedInputStep | stringInputStep | commandStep | nestedCommandStep | waitStep | nestedWaitStep | stringWaitStep | triggerStep | nestedTriggerStep[] required

A list of steps

minItems=1
depends_on null | string | dependsOnList

The step keys for a step to depend on

if string

A boolean expression that omits the step when false

Examples: "build.message != 'skip me'", "build.branch == 'master'"
if_changed string | string[] | object

Agent-applied attribute: A glob pattern that omits the step from a build if it does not match any files changed in the build. Can be a single pattern, list of patterns, or an object with include/exclude attributes.

key string

A unique identifier for a step, must not resemble a UUID

Examples: "deploy-staging", "test-integration"
maxLength=100pattern=^[a-zA-Z0-9_\-:${}.,]+$
identifier key
id key
label string | null

The name to give to this group of steps

Examples: "Tests"
name string | null

The name to give to this group of steps

Examples: "Tests"
allow_dependency_failure enum

Whether to proceed with this step and further steps if a step named in the depends_on attribute fails

Default: false
Values: true false "true" "false"
notify notifySimple | notifyEmail | notifyBasecamp | notifySlack | notifyWebhook | notifyPagerduty | notifyGithubCommitStatus | notifyGithubCheck[]

Array of notification options for this step

skip boolean | string

Whether this step should be skipped. Passing a string provides a reason for skipping this command

Examples: true, false, "My reason"
pipelineSteps blockStep | nestedBlockStep | stringBlockStep | inputStep | nestedInputStep | stringInputStep | commandStep | nestedCommandStep | waitStep | nestedWaitStep | stringWaitStep | triggerStep | nestedTriggerStep | groupStep[]

A list of steps

priority integer

Priority of all jobs in the pipeline, higher priorities are assigned to agents. When set pipeline-wide, it applies to all steps that do not have their own priority key set.

Examples:
  • -1
  • 0
  • 10