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 an attribute of a step.

Usage

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

Description

Update an attribute of a step in the build

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) [$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) [$BUILDKITE_BUILD_ID]
• --append - Append to current attribute instead of replacing it [$BUILDKITE_STEP_UPDATE_APPEND]
• --agent-access-token value - The access token used to identify the agent [$BUILDKITE_AGENT_ACCESS_TOKEN]
• --endpoint value - The Agent API endpoint (default: "https://agent.buildkite.com/v3") [$BUILDKITE_AGENT_ENDPOINT]
• --no-http2 - Disable HTTP2 when communicating with the Agent API. [$BUILDKITE_NO_HTTP2]
• --debug-http - Enable HTTP debug mode, which dumps all request and response bodies to the log [$BUILDKITE_AGENT_DEBUG_HTTP]
• --no-color - Don't show colors in logging [$BUILDKITE_AGENT_NO_COLOR]
• --debug - Enable debug mode [$BUILDKITE_AGENT_DEBUG]
• --experiment value - Enable experimental features within the buildkite-agent [$BUILDKITE_AGENT_EXPERIMENT]
• --profile value - Enable a profiling mode, either cpu, memory, mutex or block [$BUILDKITE_AGENT_PROFILE]

Getting a step

Use this command in your build scripts to get the value of a particular attribute from a step.

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 (i.e. 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 "retry" --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) [$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) [$BUILDKITE_BUILD_ID]
• --format value - The format to output the attribute value in (currently only JSON is supported) [$BUILDKITE_STEP_GET_FORMAT]
• --agent-access-token value - The access token used to identify the agent [$BUILDKITE_AGENT_ACCESS_TOKEN]
• --endpoint value - The Agent API endpoint (default: "https://agent.buildkite.com/v3") [$BUILDKITE_AGENT_ENDPOINT]
• --no-http2 - Disable HTTP2 when communicating with the Agent API. [$BUILDKITE_NO_HTTP2]
• --debug-http - Enable HTTP debug mode, which dumps all request and response bodies to the log [$BUILDKITE_AGENT_DEBUG_HTTP]
• --no-color - Don't show colors in logging [$BUILDKITE_AGENT_NO_COLOR]
• --debug - Enable debug mode [$BUILDKITE_AGENT_DEBUG]
• --experiment value - Enable experimental features within the buildkite-agent [$BUILDKITE_AGENT_EXPERIMENT]
• --profile value - Enable a profiling mode, either cpu, memory, mutex or block [$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