Buildkite Cheat Sheet

Buildkite CI/CD pipelines covering pipeline.yml syntax, agent hooks, plugins, and self-hosted agent management.

2 PagesIntermediateApr 9, 2026

pipeline.yml Basics

A typical Buildkite pipeline with parallel steps and a wait.

yaml

steps:  - label: ":hammer: Build"    command: "make build"    key: build  - wait  - label: ":test_tube: Test %n"    command: "make test"    parallelism: 4    agents:      queue: "default"    plugins:      - docker#v5.11.0:          image: "node:20"  - block: ":rocket: Deploy to prod?"    branches: "main"  - label: ":shipit: Deploy"    command: "./scripts/deploy.sh"    depends_on: build    if: build.branch == "main"

buildkite-agent CLI

Commands run inside a pipeline step, often in agent hooks.

bash

# Upload dynamically generated pipeline stepsbuildkite-agent pipeline upload .buildkite/deploy-pipeline.yml# Set a build-wide metadata key (readable by later steps)buildkite-agent meta-data set "release-version" "1.4.2"buildkite-agent meta-data get "release-version"# Upload/download artifacts between stepsbuildkite-agent artifact upload "dist/**/*"buildkite-agent artifact download "dist/**/*" .# Annotate the build UI with markdownbuildkite-agent annotate "Coverage: 87%" --style "info"

Agent Hook Example

A pre-command hook on a self-hosted agent for shared setup logic.

bash

#!/bin/bash# .buildkite/hooks/pre-commandset -euo pipefailecho "--- :docker: Logging into registry"echo "$DOCKER_PASSWORD" | docker login -u "$DOCKER_USER" --password-stdinexport NODE_ENV=test

Core Concepts

Terminology you'll see throughout Buildkite docs and the UI.

Pipeline- a named collection of steps, defined in YAML, tied to a repo
Step (command/wait/block/trigger/group)- the unit of work; block pauses for manual approval, trigger fires another pipeline
Agent- a process you run on your own infra that polls for and executes jobs
Queue- a tag used to route jobs to specific agent pools, e.g. `queue=mac` or `queue=gpu`
Plugin- a reusable YAML+hook bundle (e.g. docker#v5, ecr#v2) referenced by version tag
Dynamic pipelines- steps generated at runtime via `buildkite-agent pipeline upload`

Pro Tip

Pin every plugin to an exact version tag (`docker#v5.11.0`, not `docker#v5`) in pipeline.yml — Buildkite plugins are just git repos, and an unpinned major-version reference can silently pull a breaking update into your build.

Was this cheat sheet helpful?

Kustomize Cheat Sheet

Renovate Bot Cheat Sheet