English for Buildkite Developers

Buildkite conversations center on its hybrid model — the control plane is hosted, but the agents that actually run builds are yours — so the vocabulary covers agent management, pipeline steps, and the queueing model that connects the two.

Key Vocabulary

Agent — a process you run on your own infrastructure that polls Buildkite for jobs and executes them, meaning build steps run wherever you host the agent, not on Buildkite’s servers. “Builds are queuing because we only have two agents online — scale the agent pool, since Buildkite itself isn’t the bottleneck here, our own infrastructure is.”

Pipeline — a defined sequence of steps that Buildkite runs when triggered, typically expressed in YAML and capable of dynamically generating further steps at runtime. “This pipeline uploads new steps dynamically based on what changed in the diff — it’s not a fixed step list, so check the generation script if something looks missing.”

Queue — a named grouping that routes specific jobs to specific sets of agents, letting teams dedicate certain agents to certain kinds of work (like GPU jobs or macOS builds). “Tag this step for the GPU queue explicitly — otherwise it’ll land on a generic agent that doesn’t have the hardware this job actually needs.”

Hybrid architecture — Buildkite’s split between a hosted control plane (scheduling, UI, API) and self-hosted agents (actual job execution), giving teams infrastructure control without managing the whole CI product. “We’re not exposing source code to a third party’s build servers — the hybrid architecture means our code only ever touches agents we run ourselves.”

Artifact — a file uploaded from one step and made available for download by later steps or for inspection after the build, similar in purpose to artifacts in other CI systems. “Upload the test report as an artifact instead of only printing it to the log — that way it’s downloadable and diffable across runs, not just scrollback text.”

Common Phrases

• “Are we short on agent capacity, or is something else causing this build queue backlog?”
• “Is this pipeline generating steps dynamically, or is the step list actually fixed?”
• “Is this job tagged for the right queue, or could it land on an agent without the hardware it needs?”
• “Should this output be uploaded as an artifact, or is printing it to the log enough here?”

Example Sentences

Diagnosing a slow CI queue: “This isn’t a pipeline configuration problem — we simply don’t have enough agents online to keep up with concurrent builds, so let’s scale the agent pool first.”

Explaining the security model to a security reviewer: “Our source never leaves our own infrastructure — Buildkite’s hosted side only handles scheduling and the UI, and the agents that actually check out code run on servers we control.”

Reviewing a misrouted job: “This GPU-dependent step isn’t tagged for the GPU queue, so it’s been landing on a generic agent and failing — tag it correctly and it’ll route to hardware that can actually run it.”

Professional Tips

• Diagnose queue backlogs by checking agent capacity before assuming a pipeline configuration issue — it’s the more common root cause.
• Understand and explain the hybrid architecture clearly when security or compliance reviewers ask where code is executed — it’s a genuine differentiator worth being precise about.
• Use queues deliberately to route specialized jobs (GPU, macOS, arm64) to the agents equipped for them — misrouted jobs are a frequent, confusing failure mode.
• Upload meaningful outputs as artifacts rather than relying on log scrollback — it makes results diffable across runs and easier to share.

Practice Exercise

1. Explain to a teammate why a growing build queue points to agent capacity rather than pipeline configuration.
2. Describe Buildkite’s hybrid architecture in one or two sentences to someone doing a security review.
3. Write a sentence flagging that a GPU-dependent job isn’t tagged for the correct queue.