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.
On this page:
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) |
---|---|
--build value #
|
The build to look for the step in. Only required when targeting a step using its key (BUILDKITE_STEP_KEY) |
--append #
|
Append to current attribute instead of replacing it |
--agent-access-token value #
|
The access token used to identify the agent |
--endpoint value #
|
The Agent API endpoint (default: " |
--no-http2 #
|
Disable HTTP2 when communicating with the Agent API. |
--debug-http #
|
Enable HTTP debug mode, which dumps all request and response bodies to the log |
--no-color #
|
Don't show colors in logging |
--debug #
|
Enable debug mode |
--experiment value #
|
Enable experimental features within the buildkite-agent |
--profile value #
|
Enable a profiling mode, either cpu, memory, mutex or block |
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 (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) |
---|---|
--build value #
|
The build to look for the step in. Only required when targeting a step using its key (BUILDKITE_STEP_KEY) |
--format value #
|
The format to output the attribute value in (currently only JSON is supported) |
--agent-access-token value #
|
The access token used to identify the agent |
--endpoint value #
|
The Agent API endpoint (default: " |
--no-http2 #
|
Disable HTTP2 when communicating with the Agent API. |
--debug-http #
|
Enable HTTP debug mode, which dumps all request and response bodies to the log |
--no-color #
|
Don't show colors in logging |
--debug #
|
Enable debug mode |
--experiment value #
|
Enable experimental features within the buildkite-agent |
--profile value #
|
Enable a profiling mode, either cpu, memory, mutex or block |
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