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.
Setting data
The agent's 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 set command.
Getting data
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 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.
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.