What does the agents field control?

Buildkite routes each step to an agent whose tags match the `agents:` key-value pairs you specify, for example `queue=default` or `os=linux`. It's a comma-separated list here (e.g. `queue=default, os=linux`), parsed into the matching YAML block for the step.

What's the difference between a wait step and a block step?

A `wait` step pauses the pipeline until every step before it finishes, then continues automatically, useful for fan-in points. A `block` step also pauses the pipeline, but requires a human to click "Unblock" in the Buildkite UI before it continues, which is how manual approval gates (e.g. before a production deploy) are implemented.

Why is my command rendered as a list instead of a single string?

If you enter more than one command line for a step, Buildkite's `command:` key accepts a YAML list, and each line becomes its own list entry, run in order within that step. A single command line is rendered as a plain string instead, matching Buildkite's own convention for the common case.

What are artifact_paths used for?

Any file paths listed there are uploaded as build artifacts after the step completes, viewable and downloadable from the Buildkite build page, and available to later steps via `buildkite-agent artifact download`.

Buildkite Pipeline Generator - Build pipeline.yml

Overview

Introduction

Buildkite's pipeline.yml is deliberately minimal compared to some other CI systems, but that minimalism means small omissions, like forgetting `agents:` tags or the block-step syntax for manual approval, are easy to miss when writing it by hand.

This tool generates a complete pipeline.yml from a form: command steps, agent targeting, a wait step, artifact paths, and an optional manual-approval block step.

What Is Buildkite Pipeline Generator?

A form-driven generator for Buildkite pipeline configuration. You add one or more steps, each with a label, one or more commands, and optional agent-targeting tags, then optionally add a wait step, shared artifact paths, and a manual-approval block step.

The output is the plain YAML list Buildkite expects under its top-level `steps:` key, with each step type (command, wait, block) rendered in Buildkite's documented shape.

How Buildkite Pipeline Generator Works

Each step's agent-targeting field is parsed from a simple `key=value, key=value` string into the `agents:` mapping Buildkite expects, and multi-line commands become a YAML list under `command:` rather than a single string.

The wait and block steps, if enabled, are appended after all command steps, in Buildkite's documented shorthand form (`- wait` and `- block: "label"`).

When To Use Buildkite Pipeline Generator

Use it when setting up Buildkite for a new pipeline and you want a working pipeline.yml with correct agent targeting and step syntax from the start.

It's also useful for adding a manual approval gate before a deploy step to an existing pipeline without needing to look up Buildkite's block-step syntax.

Often used alongside GitLab CI Generator, Drone CI Generator and CircleCI Config Generator.

Features

Advantages

Correctly parses agent-targeting tags into Buildkite's `agents:` mapping instead of requiring you to remember the YAML shape.
Automatically switches between a single-string and list form for `command:` depending on whether you entered one or multiple command lines, matching Buildkite's own conventions.
Generates the wait and block step shorthand syntax exactly as Buildkite's documentation shows it.

Limitations

Doesn't cover trigger steps, step-level `if:`/`branches:` conditionals, or dynamic pipeline uploads via `buildkite-agent pipeline upload`.
Artifact paths are applied to every command step rather than per-step, split them manually afterward if only specific steps should upload artifacts.

Examples

A build step followed by a manual-approval deploy gate

Input

step 'Build' (command: npm install / npm run build, agents: queue=default); block step: 'Deploy to production?'

Output

steps:
  - label: "Build"
    command:
      - "npm install"
      - "npm run build"
    agents:
      queue: "default"

  - block: "Deploy to production?"

Two command lines become a YAML list under `command:`, the agent-targeting string is parsed into the `agents:` mapping, and the block step is appended as manual approval.

Best Practices & Notes

Best Practices

Use `agents:` tags to route steps to appropriately sized or specialized agents (e.g. a GPU queue) rather than letting Buildkite pick an arbitrary agent for demanding steps.
Add a block step immediately before any production deploy step so a human has to explicitly approve the release.
Set artifact_paths on build steps that produce output later steps or humans need, like test reports or compiled binaries.

Developer Notes

Agent-targeting is parsed from a flat `key=value` comma-separated string into Buildkite's `agents:` mapping since that's a friendlier input than raw YAML for a form field; pairs missing either a key or a value are silently dropped rather than producing invalid YAML. Single-command steps render `command:` as a scalar string (not a one-item list) to match the more common style seen in Buildkite's own examples.

Buildkite Pipeline Generator Use Cases

Scaffolding a new Buildkite pipeline.yml for a repository
Adding a manual approval gate before a production deploy step
Producing a working multi-step pipeline with artifact uploads for a build

Common Mistakes

Forgetting agent tags entirely and letting Buildkite dispatch a demanding step to an underpowered or mismatched agent.
Using a wait step where a block step was intended (or vice versa), a wait step continues automatically and provides no actual manual gate before a deploy.

Tips

Combine a wait step right before a block step if you want all prior build/test steps to finish first, then require explicit human approval before deploying.

Buildkite Pipeline Generator