buildkite-agent pipeline upload: Validate and Upload
buildkite-agent pipeline upload parses a pipeline.yml, interpolates environment variables, and uploads the steps; with --dry-run it validates and prints the result instead of uploading.
Buildkite pipelines are often generated dynamically, so validation happens at upload time. The --dry-run flag lets you check a pipeline file for parse and interpolation errors without adding steps to a build.
What it does
buildkite-agent pipeline upload reads a YAML pipeline (default .buildkite/pipeline.yml), interpolates $VAR and ${VAR} references from the environment, and uploads the resulting steps to the current build. --dry-run outputs the parsed pipeline instead of uploading, so it doubles as a validator.
Common usage
buildkite-agent pipeline upload
buildkite-agent pipeline upload .buildkite/pipeline.yml
buildkite-agent pipeline upload --dry-run # validate, do not upload
buildkite-agent pipeline upload --no-interpolation # skip env interpolationOptions
| Flag | What it does |
|---|---|
| [file] | Pipeline file (defaults to .buildkite/pipeline.yml) |
| --dry-run | Parse and print the pipeline without uploading |
| --no-interpolation | Do not interpolate environment variables |
| --format <fmt> | Output format for dry-run: yaml or json |
| --replace | Replace the rest of the existing pipeline |
In CI
Run buildkite-agent pipeline upload --dry-run in a lint step (or a plain buildkite-agent install in another CI) to catch YAML and interpolation errors before they break a real build. Because Buildkite steps are dynamic, this is the closest thing to a config validator.
Common errors in CI
Parse failures read Failed to parse ...: yaml: line N: .... Interpolation errors look like Failed to interpolate ...: \$MISSING: not set when a referenced variable is undefined; add --no-interpolation or define the variable. buildkite-agent: command not found means the agent binary is not on PATH.