Command Steps

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

On this page:

Command Step Attributes
Retry Attributes
Automatic Retry Attributes
Manual Retry Attributes
Soft Fail Attributes
Examples

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

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"`
`id`	A string to identify the step. The value is available in the `BUILDKITE_STEP_IDENTIFIER` 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