Using Build Meta-data

In this guide we’ll walk through using the Buildkite Agent’s meta-data command to store and retrieve data between different steps in a build pipeline.

Meta-data is intended for storing small pieces of information about your builds and steps to be used across steps. For example, you can tag a build with the software version it deploys so that you can later identify which build deployed a particular version. Values larger than 1 kilobyte are discouraged and should use artifacts instead.

Setting data

You can set meta-data via the command line or in a script. Both of these methods use the buildkite-agent cli with the meta-data command.

To set meta-data in the meta-data store, use the set command with a key/value pair:

buildkite-agent meta-data set "release-version" "1.1"

This command results in the value "1.1" being associated with the key "release-version" in the meta-data store.

Getting data

You can retrieve data from the meta-data store either via the command line or in a script. The same as when setting data, both of these methods use the buildkite-agent cli with the meta-data command.

Values can only be retrieved from the store after it has been set - ensure that any steps that are getting data are guaranteed to run after the completion of the step that sets the data. One way to ensure workflows in this way is to use a wait step.

To retrieve meta-data, use the get command with the previously set key:

buildkite-agent meta-data get "release-version"

Assuming that the "release-version" key was set with the value from the Setting Data example, this command will return "1.1". If there are no keys matching the name "release-version", it will return an error.

Default values

The `get` command has a `default` flag. You can use this to return a value in the case that the key has not been set.

Using Meta-data on the Dashboard

Meta-data is not widely exposed in the Buildkite Dashboard, but it can be added to most builds URLs to filter down the list of builds shown to only those with certain meta-data.

To list builds in a pipeline which have a "release-version" of "1.1" you could use:

https://buildkite.com/my-organization/my-pipeline/builds?meta_data[release-version]=1.1

Using Meta-data in the REST API

You can use meta-data to identify builds when searching for builds in the REST API:

https://buildkite.com/docs/apis/rest-api/builds

For more information see the Buildkite REST Builds API documentation.

Further documentation

See the Buildkite Agent build meta-data documentation for a full list of options and details of Buildkite’s meta-data support.