developing-pipelines

Developing Buildkite Pipelines

Overview

Reference official Buildkite documentation before making pipeline changes. Your training data may contain outdated syntax, deprecated patterns, or missing features.

When to Use

Use this skill when:

• Writing or modifying pipeline.yml files
• Creating dynamic pipelines
• Debugging pipeline configuration errors
• Adding new step types (command, trigger, block, wait)
• Configuring dependencies, artifacts, or parallelism
• Setting up Buildkite plugins
• Configuring or debugging Buildkite plugins

Do NOT use for:

• Checking build status (use buildkite-status skill)
• General CI/CD concepts (language-agnostic advice)

The Iron Rule

NEVER propose Buildkite YAML without consulting the reference docs.

Detecting buildkite-builder

Check for buildkite-builder usage before proceeding:

buildkite-builder is detected when BOTH conditions are true:

1. .buildkite/pipeline.yml references Docker image containing "buildkite-builder"
2. Pipeline Ruby files exist: .buildkite/pipeline.rb OR .buildkite/pipelines/*/pipeline.rb

When detected, announce:

"I see you're using buildkite-builder for dynamic pipeline generation. I'll work with your pipeline.rb files and reference the Ruby DSL."

Then load buildkite-builder reference documentation as needed.

Working with Plugins

Before Modifying Plugin Configuration

When editing pipeline steps that use plugins:

1. Identify plugins - Note all plugins: entries in the step
2. Determine source:
   • Default org buildkite-plugins if no org specified
   • Parse explicit org from {org}/{plugin}#version format
3. Load documentation:
   • Cached: Check references/plugins/{plugin-name}.md
   • Official (not cached): Fetch from Buildkite directory or GitHub
   • Internal: Fetch README from github.com/{org}/{plugin}-buildkite-plugin
4. Match versions - If pipeline specifies version, fetch that version's docs from GitHub tag