buildkite-agent meta-data

The Buildkite Agent’s meta-data command provides your build pipeline with a powerful key/value data-store that works across build steps and build agents, no matter the machine or network.

See the Using Build Meta-data guide for a step-by-step example.

Setting data

Use this command in your build scripts to save string data in the Buildkite meta-data store.

Usage

buildkite-agent meta-data set <key> [value] [options...]

Description

Set arbitrary data on a build using a basic key/value store.

You can supply the value as an argument to the command, or pipe in a file or script output.

Example

$ buildkite-agent meta-data set "foo" "bar"
$ buildkite-agent meta-data set "foo" < ./tmp/meta-data-value
$ ./script/meta-data-generator | buildkite-agent meta-data set "foo"

Options

  • --job value - Which job's build should the meta-data be set on [$BUILDKITE_JOB_ID]
  • --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]

Meta-data values are restricted to a maximum of 100 kilobytes. Keys and values larger than 1 kilobyte are discouraged. Please use artifacts for large data which needs to uploaded and downloaded.

Getting data

Use this command in your build scripts to get a previously saved value from the Buildkite meta-data store.

Usage

buildkite-agent meta-data get <key> [options...]

Description

Get data from a builds key/value store.

Example

$ buildkite-agent meta-data get "foo"

Options

  • --default value - If the meta-data value doesn't exist return this instead
  • --job value - Which job's build should the meta-data be retrieved from [$BUILDKITE_JOB_ID]
  • --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]

Checking if data exists

Usage

buildkite-agent meta-data exists <key> [options...]

Description

The command exits with a status of 0 if the key has been set, or it will exit with a status of 100 if the key doesn't exist.

Example

$ buildkite-agent meta-data exists "foo"

Options

  • --job value - Which job's build should the meta-data be checked for [$BUILDKITE_JOB_ID]
  • --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]

Listing keys

Usage

buildkite-agent meta-data keys [options...]

Description

Lists all meta-data keys that have been previously set, delimited by a newline and terminated with a trailing newline.

Example

$ buildkite-agent meta-data keys

Options

  • --job value - Which job's build should the meta-data be checked for [$BUILDKITE_JOB_ID]
  • --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]