buildkite-agent pipeline

The Buildkite Agent’s pipeline command allows you to add and replace build steps in the running build. The steps are defined using YML or JSON and can be read from a file or streamed from the output of a script.

See the Uploading Build Pipelines guide for a step-by-step example.

Uploading Pipelines


   buildkite-agent pipeline upload <file> [arguments...]


   Allows you to change the pipeline of a running build by uploading either a
   JSON or YAML configuration file. If no configuration file is provided,
   we look for the file in the following locations:

   - .buildkite/pipeline.yml
   - .buildkite/pipeline.json

   You can also pipe build pipelines to the command, allowing you to create scripts
   that generate dynamic pipelines.


   $ buildkite-agent pipeline upload
   $ buildkite-agent pipeline upload my-custom-steps.json
   $ ./script/dynamic_step_generator | buildkite-agent pipeline upload


   --replace                                    Replace the rest of the existing pipeline with the steps uploaded. Jobs that are already running are not removed. [$BUILDKITE_PIPELINE_REPLACE]
   --job                                        The job that is making the changes to it's build [$BUILDKITE_JOB_ID]
   --agent-access-token                         The access token used to identify the agent [$BUILDKITE_AGENT_ACCESS_TOKEN]
   --endpoint ""  The Agent API endpoint [$BUILDKITE_AGENT_ENDPOINT]
   --no-color                                   Don't show colors in logging [$BUILDKITE_AGENT_NO_COLOR]
   --debug                                      Enable debug mode [$BUILDKITE_AGENT_DEBUG]
   --debug-http                                 Enable HTTP debug mode, which dumps all request and response bodies to the log [$BUILDKITE_AGENT_DEBUG_HTTP]

Pipeline Format

The pipeline can be written as YAML or JSON, but YAML is more commonly for its readability. There are two top level properties you can specify:

  • env - a hash of build-wide environment variables
  • steps - an array of build steps to be run (a mix of script, wait and block steps)