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
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 YAML list.
Example: "build.sh"
Example:
- "npm install"
- "tests.sh"

steps:
  - command: "npm install && tests.sh"

steps:
  - command:
    - "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 YAML 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"`
`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`	A map 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. 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"`
`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 cancelled and the build will fail. Example: `60`

Retry Attributes

At least one of the following attributes is required.

You don't have to set both the automatic and manual attributes on retry, but you can choose to set both.

`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: "Linting"
    command: "lint.sh"
    retry:
      manual: false
  - label: "Tests"
    command: "tests.sh"
    retry:
      automatic: true

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

An exit status of -1 results when a job loses connection with the agent running it. Jobs that exit with -1 will be automatically retried, unless you have overridden the retry behavior in the pipeline.yml file.

steps:
  - label: "Linting"
    command: "lint.sh"
    retry:
      automatic:
        limit: 3
  - label: "Visual Diffs"
    command: "diffs.sh"
    retry:
      automatic:
        exit_status: 1
        limit: 1
  - label: "Tests"
    command: "tests.sh"
    retry:
      automatic:
        - exit_status: 5
          limit: 2
        - exit_status: "*"
          limit: 4

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: "Linting"
    command: "lint.sh"
    retry:
      manual: true
  - label: "Visual Diffs"
    command: "diffs.sh"
    retry:
      manual:
        allowed: false
        reason: "Don't run this twice, it's not flaky"
  - label: "Tests"
    command: "tests.sh"
    retry:
      manual:
        permit_on_passed: true

Examples

steps:
  - label: ":hammer: Tests"
    command:
      - "npm install"
      - "tests.sh"
    branches: "master"
    env:
      RAILS_ENV: "test"
      RACK_ENV: "test"
    agents:
      npm: "true"
      queue: "tests"
    artifact_paths:
      - "logs/**/*"
      - "coverage/**/*"
    parallelism: 1
    timeout_in_minutes: 60
    retry:
      automatic:
        - exit_status: 1
          limit: 3
        - exit_status: 75
          limit: 5
  - label: "Linting"
    command: "lint.sh"
    retry:
      manual: false
      automatic:
        limit: 3
  - wait
  - label: ":shipit: Deploy"
    command: "deploy.sh"
    branches: "master"
    concurrency: 1
    concurrency_group: "my-app/deploy"
    retry:
      manual:
        allowed: false
        reason: "Don't retry deploys please!"
  - label: "Skipped job"
    command: "my_command.sh"
    skip: "Didn't feel like it"