Command Steps

A command step runs one or more shell commands on an agent.

Each command step can run either a shell command like npm install, or an executable file or script like build.sh.

Screenshot of a basic command step

A basic command step can be defined in your pipeline settings, or in your pipeline.yml file.

steps:
  - command: "tests.sh"

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"
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"
env A map of environment variables for this step.
Example: RAILS_ENV: "test"
key A unique string to identify the step. The value is available in the BUILDKITE_STEP_KEY environment variable.
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:
    run: app
retry The conditions for retrying this step.
Available retry 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 Should this step cause the build to fail if it exits with a non-zero status. Can be either an array of soft failure exit statuses or true to make all exit statuses soft-fail.
Example: true
Example:
- exit_status: 1
- exit_status: "*"
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 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).

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 The exit status number that will cause this job to be soft-failed.
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