buildkite-agent step

The Buildkite agent's step command provides the ability to retrieve and update the attributes of steps in your pipeline.yml files.

Updating a step

Use this command in your build scripts to update the label attribute of a step.

Usage

buildkite-agent step update <attribute> <value> [options...]

Description

Update an attribute of a step in the build

Note that step labels are used in commit status updates, so if you change the label of a running step, you may end up with an 'orphaned' status update under the old label, as well as new ones using the updated label.

To avoid orphaned status updates, in your Pipeline Settings > GitHub:

Make sure Update commit statuses is not selected. Note that this prevents Buildkite from automatically creating and sending statuses for this pipeline, meaning you will have to handle all commit statuses through the pipeline.yml

Example

$ buildkite-agent step update "label" "New Label"
$ buildkite-agent step update "label" " (add to end of label)" --append
$ buildkite-agent step update "label" < ./tmp/some-new-label
$ ./script/label-generator | buildkite-agent step update "label"

Options

`--step value` #	The step to update. Can be either its ID (BUILDKITE_STEP_ID) or key (BUILDKITE_STEP_KEY) Environment variable: `$BUILDKITE_STEP_ID`
`--build value` #	The build to look for the step in. Only required when targeting a step using its key (BUILDKITE_STEP_KEY) Environment variable: `$BUILDKITE_BUILD_ID`
`--append` #	Append to current attribute instead of replacing it Environment variable: `$BUILDKITE_STEP_UPDATE_APPEND`
`--agent-access-token value` #	The access token used to identify the agent Environment variable: `$BUILDKITE_AGENT_ACCESS_TOKEN`
`--endpoint value` #	The Agent API endpoint (default: "`https://agent.buildkite.com/v3`") Environment variable: `$BUILDKITE_AGENT_ENDPOINT`
`--no-http2` #	Disable HTTP2 when communicating with the Agent API. Environment variable: `$BUILDKITE_NO_HTTP2`
`--debug-http` #	Enable HTTP debug mode, which dumps all request and response bodies to the log Environment variable: `$BUILDKITE_AGENT_DEBUG_HTTP`
`--no-color` #	Don't show colors in logging Environment variable: `$BUILDKITE_AGENT_NO_COLOR`
`--debug` #	Enable debug mode. Synonym for `--log-level debug`. Takes precedence over `--log-level` Environment variable: `$BUILDKITE_AGENT_DEBUG`
`--log-level value` #	Set the log level for the agent, making logging more or less verbose. Defaults to notice. Allowed values are: debug, info, error, warn, fatal (default: "notice") Environment variable: `$BUILDKITE_AGENT_LOG_LEVEL`
`--experiment value` #	Enable experimental features within the buildkite-agent Environment variable: `$BUILDKITE_AGENT_EXPERIMENT`
`--profile value` #	Enable a profiling mode, either cpu, memory, mutex or block Environment variable: `$BUILDKITE_AGENT_PROFILE`

Getting a step

Use this command in your build scripts to get the value of a particular attribute from a step. The following attributes values can be retrieved:

agents
command
concurrency_key
concurrency_limit
depends_on
env
if
key
label
notify
outcome
parallelism
state
timeout
type

Usage

buildkite-agent step get <attribute> [options...]

Description

Retrieve the value of an attribute in a step. If no attribute is passed, the entire step will be returned.

In the event a complex object is returned (an object or an array), you'll need to supply the --format option to tell the agent how it should output the data (currently only JSON is supported).

Example

$ buildkite-agent step get "label" --step "key"
$ buildkite-agent step get --format json
$ buildkite-agent step get "state" --step "my-other-step"

Options

`--step value` #	The step to get. Can be either its ID (BUILDKITE_STEP_ID) or key (BUILDKITE_STEP_KEY) Environment variable: `$BUILDKITE_STEP_ID`
`--build value` #	The build to look for the step in. Only required when targeting a step using its key (BUILDKITE_STEP_KEY) Environment variable: `$BUILDKITE_BUILD_ID`
`--format value` #	The format to output the attribute value in (currently only JSON is supported) Environment variable: `$BUILDKITE_STEP_GET_FORMAT`
`--agent-access-token value` #	The access token used to identify the agent Environment variable: `$BUILDKITE_AGENT_ACCESS_TOKEN`
`--endpoint value` #	The Agent API endpoint (default: "`https://agent.buildkite.com/v3`") Environment variable: `$BUILDKITE_AGENT_ENDPOINT`
`--no-http2` #	Disable HTTP2 when communicating with the Agent API. Environment variable: `$BUILDKITE_NO_HTTP2`
`--debug-http` #	Enable HTTP debug mode, which dumps all request and response bodies to the log Environment variable: `$BUILDKITE_AGENT_DEBUG_HTTP`
`--no-color` #	Don't show colors in logging Environment variable: `$BUILDKITE_AGENT_NO_COLOR`
`--debug` #	Enable debug mode. Synonym for `--log-level debug`. Takes precedence over `--log-level` Environment variable: `$BUILDKITE_AGENT_DEBUG`
`--log-level value` #	Set the log level for the agent, making logging more or less verbose. Defaults to notice. Allowed values are: debug, info, error, warn, fatal (default: "notice") Environment variable: `$BUILDKITE_AGENT_LOG_LEVEL`
`--experiment value` #	Enable experimental features within the buildkite-agent Environment variable: `$BUILDKITE_AGENT_EXPERIMENT`
`--profile value` #	Enable a profiling mode, either cpu, memory, mutex or block Environment variable: `$BUILDKITE_AGENT_PROFILE`

Getting the outcome of a step

If you're only interested in whether a step passed or failed, perhaps to use conditional logic inside your build script, you can use the same approach as above in Getting a step.

For example, the following pipeline has one step that fails (one), and another that passes (two). After the wait, the next two steps print the outcome attribute of steps one and two, and the last step annotates the build if step one fails. Note that step get needs the key of the step to identify it, not the label.

The outcome is passed, hard_failed or soft_failed. A soft fail is a non-zero exit status that does not fail the build.

steps:
  - label: 'Step 1'
    command: "false"
    key: 'one'
  - label: 'Step 2'
    command: "true"
    key: 'two'

  - wait:
    continue_on_failure: true

  - label: 'Step 3'
    command: 'echo `buildkite-agent step get "outcome" --step "one"`'
  - label: 'Step 4'
    command: 'echo `buildkite-agent step get "outcome" --step "two"`'
  - label: 'Step 5'
    command: |
      if [ $(buildkite-agent step get "outcome" --step "one") == "hard_failed" ]; then
        buildkite-agent annotate 'this build failed' --style 'error'
      fi

$ buildkite-agent step cancel --step "key"
$ buildkite-agent step cancel --step "key" --force
$ buildkite-agent step cancel --step "key" --force --force-grace-period-seconds 30

Options

`--step value` #	The step to cancel. Can be either its ID (BUILDKITE_STEP_ID) or key (BUILDKITE_STEP_KEY) Environment variable: `$BUILDKITE_STEP_ID`
`--force` #	Transition unfinished jobs to a canceled state instead of waiting for jobs to finish uploading artifacts Environment variable: `$BUILDKITE_STEP_CANCEL_FORCE`
`--force-grace-period-seconds value` #	The number of seconds to wait for agents to finish uploading artifacts before transitioning unfinished jobs to a canceled state. `--force` must also be supplied for this to take affect (default: 10) [$BUILDKITE_STEP_CANCEL_FORCE_GRACE_PERIOD_SECONDS, $BUILDKITE_CANCEL_GRACE_PERIOD] Environment variable: `$BUILDKITE_STEP_CANCEL_FORCE_GRACE_PERIOD_SECONDS`
`--agent-access-token value` #	The access token used to identify the agent Environment variable: `$BUILDKITE_AGENT_ACCESS_TOKEN`
`--endpoint value` #	The Agent API endpoint (default: "`https://agent.buildkite.com/v3`") Environment variable: `$BUILDKITE_AGENT_ENDPOINT`
`--no-http2` #	Disable HTTP2 when communicating with the Agent API. Environment variable: `$BUILDKITE_NO_HTTP2`
`--debug-http` #	Enable HTTP debug mode, which dumps all request and response bodies to the log Environment variable: `$BUILDKITE_AGENT_DEBUG_HTTP`
`--no-color` #	Don't show colors in logging Environment variable: `$BUILDKITE_AGENT_NO_COLOR`
`--debug` #	Enable debug mode. Synonym for `--log-level debug`. Takes precedence over `--log-level` Environment variable: `$BUILDKITE_AGENT_DEBUG`
`--log-level value` #	Set the log level for the agent, making logging more or less verbose. Defaults to notice. Allowed values are: debug, info, error, warn, fatal (default: "notice") Environment variable: `$BUILDKITE_AGENT_LOG_LEVEL`
`--experiment value` #	Enable experimental features within the buildkite-agent Environment variable: `$BUILDKITE_AGENT_EXPERIMENT`
`--profile value` #	Enable a profiling mode, either cpu, memory, mutex or block Environment variable: `$BUILDKITE_AGENT_PROFILE`