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 to store data 1 kilobyte or less in size, 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. For anything over 1 kb use an artifact instead.
meta-data command is the only method for setting meta-data. You can run the command from the command line or in a script.
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.
Once meta-data is set for a build, it cannot be deleted. It can only be updated using the
You can retrieve data from the meta-data store either using the command line or in a script. The same as when setting data, both of these methods use the
buildkite-agent cli with the
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.
get command has a
default flag. You can use this to return a value in the case that the key has not been set.
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:
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.
See the Buildkite agent build meta-data documentation for a full list of options and details of Buildkite's meta-data support.