Command Step
A command step runs one or more shell commands on one or more agents.
On this page:
Each command step can run either a shell command like npm test
, or an executable file or script like build.sh
.
A command step can be defined in your pipeline settings, or in your pipeline.yml file.
steps:
- command: "tests.sh"
When running multiple commands, either defined in a single line (npm install && tests.sh
) or defined in a list, any failure will prevent subsequent commands from running, and will mark the command step as failed.
Command Step Attributes
Required attributes:
command |
The shell command/s to run during this step. This can be a single line of commands, or a list of commands that must all pass. Also available as the alias commands .Example: "build.sh" Example: - "npm install" - "tests.sh"
|
steps:
- command: "npm install && tests.sh"
steps:
- commands:
- "npm install && npm test"
- "moretests.sh"
- "build.sh"
Optional attributes:
agents |
A map of agent tag keys to values to target specific agents for this step. Example: npm: "true"
|
allow_dependency_failure |
Whether to continue to run this step if any of the steps named in the depends_on attribute fail.Default: false
|
artifact_paths |
The glob path or paths of artifacts to upload from this step. This can be a single line of paths separated by semicolons, or a list. Example: "logs/**/*;coverage/**/*" Example: - "logs/**/*" - "coverage/**/*"
|
branches |
The branch pattern defining which branches will include this step in their builds. Example: "master stable/*"
|
concurrency |
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 a label for it with the concurrency_group attribute.Example: 3
|
concurrency_group |
A unique name for the concurrency group that you are creating with the concurrency attribute.Example: "my-app/deploy"
|
depends_on |
A list of step keys that this step depends on. This step will only run after the named steps have completed. See managing step dependencies for more information. Example: "test-suite"
|
env |
A map of environment variables for this step. Example: RAILS_ENV: "test"
|
if |
A boolean expression that omits the step when false. See Using conditionals for supported expressions. Example: build.message != "skip me"
|
key |
A unique string to identify the step. The value is available in the BUILDKITE_STEP_KEY environment variable.Keys can not have the same pattern as a UUID ( xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx ).Example: "linter"
Alias: identifier
|
label |
The label that will be displayed in the pipeline visualisation in Buildkite. Supports emoji. Example: ":hammer: Tests" |
parallelism |
The number of parallel jobs that will be created based on this step. Example: 3
|
plugins |
An array of plugins for this step. Example: - docker-compose#v1.0.0:
|
retry |
The conditions for retrying this step. Available types: automatic , manual
|
skip |
Whether to skip this step or not. Passing a string provides a reason for skipping this command. Passing an empty string is equivalent to false .
Note: Skipped steps will be hidden in the pipeline view by default, but can be made visible by toggling the 'Skipped jobs' icon.Example: true Example: false Example: "My reason"
|
soft_fail |
Allow specified non-zero exit statuses not to fail the build. Note that a timeout always causes a build to fail.
Can be either an array of allowed soft failure exit statuses or true to make all exit statuses soft-fail.Example: true Example: - exit_status: 1 |
timeout_in_minutes |
The number of minutes a job created from this step is allowed to run. If the job does not finish within this limit, it will be automatically canceled and the build will fail. Example: 60
|
Retry Attributes
At least one of the following attributes is required:
automatic |
Whether to allow a job to retry automatically. This field accepts a boolean value, individual retry conditions, or a list of multiple different retry conditions. If set to true , the retry conditions are set to the default value.Default value: exit_status: "*" limit: 2 Example: true
|
manual |
Whether to allow a job to be retried manually. This field accepts a boolean value, or a single retry condition. Default value: true Example: false
|
steps:
- label: "Tests"
command: "tests.sh"
retry:
automatic: true
- wait
- label: "Deploy"
command: "deploy.sh"
retry:
manual: false
Automatic Retry Attributes
Optional Attributes
exit_status |
The exit status number that will cause this job to retry. Example: "*" Example: 2
|
limit |
The number of times this job can be retried. The maximum value this can be set to is 10. Example: 3
|
-1 Exit Status
A job will fail with an exit status of -1 if communication with the agent has been lost (e.g. the agent has been forcefully terminated, or the agent machine was shut down without allowing the agent to disconnect). See the section on Exit Codes for information on other exit codes.
steps:
- label: "Tests"
command: "tests.sh"
retry:
automatic:
- exit_status: -1 # Agent was lost
limit: 2
- exit_status: 255 # Forced agent shutdown
limit: 2
Manual Retry Attributes
Optional Attributes
allowed |
A boolean value that defines whether or not this job can be retried manually. Default value: true Example: false
|
permit_on_passed |
A boolean value that defines whether or not this job can be retried after it has passed. Example: false
|
reason |
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.Example: "No retries allowed on deploy steps"
|
steps:
- label: "Tests"
command: "tests.sh"
retry:
manual:
permit_on_passed: true
- wait
- label: "Deploy"
command: "deploy.sh"
retry:
manual:
allowed: false
reason: "Sorry, you can't retry a deployment"
Soft Fail Attributes
Optional Attributes
exit_status |
Allow specified non-zero exit statuses not to fail the build.
Note that a timeout always causes a build to fail. Example: "*" Example: 1
|
steps:
- label: "Everyone struggles sometimes"
command: "tests.sh"
soft_fail:
- exit_status: 1
Examples
steps:
- label: ":hammer: Tests"
commands:
- "npm install"
- "npm run tests"
branches: "master"
env:
NODE_ENV: "test"
agents:
npm: "true"
queue: "tests"
artifact_paths:
- "logs/**/*"
- "coverage/**/*"
parallelism: 5
timeout_in_minutes: 3
retry:
automatic:
- exit_status: -1
limit: 2
- exit_status: 143
limit: 2
- exit_status: 255
limit: 2
- label: "Visual diff"
commands:
- "npm install"
- "npm run visual-diff"
retry:
automatic:
limit: 3
- label: "Skipped job"
command: "broken.sh"
skip: "Currently broken and needs to be fixed"
- wait
- label: ":shipit: Deploy"
command: "deploy.sh"
branches: "master"
concurrency: 1
concurrency_group: "my-app/deploy"
retry:
manual:
allowed: false
reason: "Sorry, you can't retry a deployment"
- wait
- label: "Smoke test"
command: "smoke-test.sh"
soft_fail:
- exit_status: 1