version
1.1.4
GitHub stars
13

Install

/plugin install buildkite@pickled-claude-plugins

Run it inside Claude Code after adding the marketplace with /plugin marketplace add technicalpickles/pickled-claude-plugins.

Contents

Discovered from source

Skills 2

Developing Buildkite Pipelines

Overview

Read the matching file under references/ before writing or changing pipeline YAML or pipeline.rb. Training data lags Buildkite's current syntax, plugin options, and deprecations.

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

Fetching Plugin Documentation

Buildkite directory (latest):

https://buildkite.com/resources/plugins/{org}/{plugin-name}-buildkite-plugin

GitHub README (version-specific):

https://github.com/{org}/{plugin-name}-buildkite-plugin/tree/{version}

Plugin Discovery

"Is there a plugin for X?"

  1. Check references/plugins/index.md for common plugins by category
  2. Fetch Buildkite directory: https://buildkite.com/resources/plugins/
  3. Search by task type (caching, docker, secrets, etc.)

Internal plugins:

Search org's GitHub for repos matching *-buildkite-plugin

Workflow

1. Detect buildkite-builder (if present)

buildkite-builder generates the pipeline from Ruby. It is in use when both hold:

  • .buildkite/pipeline.yml references a Docker image containing "buildkite-builder"
  • .buildkite/pipeline.rb or .buildkite/pipelines/*/pipeline.rb exists

When it is, edit the pipeline.rb files and read references/buildkite-builder/ alongside the YAML references.

2. Read the reference first

Before writing the change, read the matching file in references/ for YAML, or in references/buildkite-builder/ for pipeline.rb.

Available references:

  • step-types.md - Command, trigger, block, wait, input steps
  • dynamic-pipelines.md - Generating steps programmatically
  • dependencies.md - Using depends_on, parallel steps
  • environment-variables.md - Setting and using env vars
  • conditionals.md - if/branches for conditional execution
  • artifacts.md - Uploading and downloading build artifacts

See references/index.md for complete list.

Plugin references (see references/plugins/index.md for full list):

  • plugins/docker.md - Docker container execution
  • plugins/docker-compose.md - Multi-container environments
  • plugins/artifacts.md - Artifact upload/download
  • plugins/ecr.md - AWS ECR authentication
  • plugins/cache.md - Dependency caching

buildkite-builder references (when detected):

  • buildkite-builder/index.md - Overview and when to use
  • buildkite-builder/dsl-syntax.md - Core DSL step types
  • buildkite-builder/step-attributes.md - Common attributes
  • buildkite-builder/templates.md - Reusable step templates
  • buildkite-builder/extensions.md - Custom DSL and extensions
  • buildkite-builder/conditionals.md - Conditional step generation
  • buildkite-builder/dependencies.md - Step dependencies
  • buildkite-builder/artifacts.md - Artifact handling
  • buildkite-builder/plugins.md - Plugin usage in DSL
  • buildkite-builder/environment.md - Environment variables

See references/buildkite-builder/index.md for complete guide.

3. Validate Syntax

Validate before proposing the change. When no validator is installed, give the user the command instead.

# Schema check with the bk CLI, local, no API token
bk pipeline validate --file .buildkite/pipeline.yml

# Or with buildkite-agent, where it is installed
buildkite-agent pipeline upload --dry-run < pipeline.yml

# Or validate a generated pipeline
./generate-pipeline.sh | buildkite-agent pipeline upload --dry-run

For buildkite-builder pipelines:

After proposing pipeline.rb changes:

  1. Scan for ENV variable usage
  2. Generate Docker validation command with placeholders
  3. List detected environment variables
# Generate YAML locally
docker run --rm \
  -v $(pwd)/.buildkite:/workspace/.buildkite \
  -e BUILDKITE_BRANCH=main \
  -e BUILDKITE_COMMIT=abc123def \
  -e BUILDKITE_BUILD_NUMBER=1 \
  gusto/buildkite-builder:<tag from .buildkite/pipeline.yml>

# Validate generated YAML
docker run ... | buildkite-agent pipeline upload --dry-run

Note: List any custom ENV variables found in pipeline.rb and suggest setting real values if needed.

4. Load Plugin Documentation

For any step with a plugins: block, follow Working with Plugins before changing it.

buildkite-builder Troubleshooting Mode

When user mentions errors, "not generating", "YAML looks wrong", or validation failures with buildkite-builder:

  1. Read pipeline.rb - Understand the Ruby DSL
  2. Run Docker command - Generate YAML to see actual output
  3. Compare output - Expected vs actual YAML
  4. Reference both docs - buildkite-builder DSL AND Buildkite YAML docs
  5. Identify issue - Where Ruby DSL produces unexpected YAML
  6. Propose fix - Modify pipeline.rb to fix generation

This mode switches from Ruby-first to YAML-aware debugging.

Dynamic Pipelines Pattern

When generating steps programmatically:

  1. Reference dynamic-pipelines.md for current patterns
  2. Use Buildkite SDK if available (see dynamic-pipelines.md)
  3. Validate generated output with --dry-run
  4. Consider official examples before custom implementations
# Standard pattern from official docs
.buildkite/pipeline.sh | buildkite-agent pipeline upload

Debugging Configuration Errors

When pipeline fails with validation errors:

  1. Verify step structure in references/step-types.md
  2. Validate dependencies in references/dependencies.md
  3. Don't speculate - look up the actual validation rules

Working with Buildkite Builds

Check status, investigate failures, and reproduce them locally for Buildkite builds that already exist.

Tools, in order

Always use Buildkite-native tools. Don't fall back to gh pr view/gh pr checks or the GitHub API: GitHub shows only a summary and loses annotations, logs, and the broken-vs-failed distinction. If one Buildkite tool fails, move to the next tier below rather than abandoning Buildkite.

  1. npx bktide@latest snapshot <buildkite-url> (use this first). Parses any build or step URL, downloads build metadata, annotations, and logs for failed steps into files you can grep and re-read without more API calls. bktide snapshot --help for options, bktide prime for LLM-oriented usage.

    ./tmp/bktide/snapshots/<org>/<pipeline>/<build>/
    ├── manifest.json      # Step index with states and exit codes
    ├── build.json         # Full build metadata
    ├── annotations.json   # Build annotations
    └── steps/<NN-step-name>/{log.txt,step.json}
    
  2. Other bktide commands for quick queries: pipelines <org>, builds <org>/<pipeline>, build <org>/<pipeline>#<build>, annotations <org>/<pipeline>#<build>, and the one write capability, build create / build rebuild (see below).

  3. MCP tools (fallback, and the only way to unblock a build): buildkite:get_build, list_builds, list_annotations, get_pipeline, list_pipelines, wait_for_build, get_logs, get_logs_info, list_artifacts, unblock_job. Start with detail_level: "summary" and filter with job_state: "failed".

Full capability matrix: references/tool-capabilities.md. The tool preference order can be overridden in ~/.config/pickled-claude-plugins/buildkite.yml; a PreToolUse hook enforces it by intercepting bk CLI commands that overlap with bktide.

No URL: find the branch's build

npx bktide@latest builds <org>/<pipeline> --branch <branch> --count 1 --format json

The newest build is .builds[0] (number, state, url). Without --branch it lists every branch. Snapshot its url.

Investigating a failed build

Snapshot the URL, then:

Filter to root failures. Most builds have 1-3 root failures and dozens-to-hundreds of dependent BROKEN steps. Counting BROKEN/RUNNING steps as failures sends you down rabbit holes investigating noise.

First, see the state distribution:

jq -r '.steps[].state' ./tmp/bktide/snapshots/<org>/<pipeline>/<build>/manifest.json | sort | uniq -c | sort -rn

Only these are real failures:

  • Steps with state FINISHED (or FAILED) AND non-zero exit_status

These are NOT failures — do not count or investigate them:

  • BROKEN — Downstream dependencies that never ran. Auto-resolve when the root failure is fixed.
  • RUNNING — Still in progress.
  • WAITING / SCHEDULED — Haven't started yet.
  • CANCELED — Manually or automatically canceled.

Find actual root failures:

jq -r '.steps[] | select((.state == "FINISHED" or .state == "FAILED") and .exit_status != null and .exit_status != 0) | "\(.id): \(.label) (exit \(.exit_status))"' ./tmp/bktide/snapshots/<org>/<pipeline>/<build>/manifest.json

Example: A summary reads "466 steps: 43 passed, 397 failed, 361 running" — filtering reveals 1 actual failure (e.g. codeownership validation) and 396 BROKEN dependents. Fix the root and everything else passes.

Then read the failing step's steps/<step-id>/log.txt (or grep -r "Error\|Failed\|Exception" across steps/), and check annotations.json: large projects summarize test failures there, small ones usually have none. See references/buildkite-states.md and references/annotation-patterns.md.

Logs via MCP (when snapshot isn't an option)

mcp__MCPProxy__call_tool('buildkite:get_build', {
  org_slug: '<org>',
  pipeline_slug: '<pipeline>',
  build_number: '<build-number>',
  detail_level: 'detailed',
  job_state: 'failed',
});

Match the job by label and take its uuid, then:

mcp__MCPProxy__call_tool('buildkite:get_logs', {
  org_slug: '<org>',
  pipeline_slug: '<pipeline>',
  build_number: '<build-number>',
  job_id: '<job-uuid>',
});

Common Issues:

  • "job not found" error: You likely provided a step ID instead of a job UUID. Step IDs come from URLs (sid=019a5f...). Job UUIDs come from get_build API responses.
  • Empty logs: The job may not have started yet. Check the job's state field first.

After a push

Right after git push the branch's newest build can still be the previous one, and builds JSON has no commit, so confirm the build is for HEAD with build --format json (.commit) before watching. --no-cache keeps each poll fresh. Run the whole block in the background:

sha=$(git rev-parse HEAD); build=
for _ in $(seq 20); do  # about 5 minutes for the build to appear
  n=$(npx bktide@latest builds <org>/<pipeline> --branch <branch> --count 1 --format json --no-cache | jq -r '.builds[0].number // empty')
  if [ -n "$n" ] && [ "$(npx bktide@latest build "<org>/<pipeline>#$n" --format json --no-cache | jq -r .commit)" = "$sha" ]; then build=$n; break; fi
  sleep 15
done
if [ -n "$build" ]; then npx bktide@latest build "<org>/<pipeline>#$build" --watch; else echo "no build for $sha" >&2; (exit 2); fi

Exit 0 means passed, 1 means anything else (failed, canceled, or --timeout <minutes> reached, default 30; the timeout prints Timeout reached), 2 means no build for HEAD appeared. MCP buildkite:wait_for_build (timeout: 1800, poll_interval: 30) also works where a Buildkite MCP server is connected. Don't poll in the foreground.

Blocked builds

A blocked build waits on a manual step. Find the job with state: "blocked" in get_build (detail_level: "detailed"), check its label for what approval it needs, and unblock only if appropriate:

mcp__MCPProxy__call_tool('buildkite:unblock_job', {
  org_slug: '<org>',
  pipeline_slug: '<pipeline>',
  build_number: '<build-number>',
  job_id: '<job-id>',
  fields: {}, // Optional form fields if the block step has inputs
});

Reproducing a failure locally

  1. Extract the command from the log. Docker-compose steps log it as :docker: Running /bin/sh -e -c '<command>' in service <service>; with shell trace on, look for + lines.
  2. Find the environment: vars printed in the log, env: blocks in .buildkite/pipeline.yml (or the buildkite-builder DSL), and Buildkite defaults like CI=true (references/buildkite-environment-variables.md).
  3. Translate: run the command directly first; if it ran in Docker, docker-compose run [-e CI=true ...] <service> <command>. Drop CI-only flags (--parallel 4 to 1, --format buildkite to progress) and skip buildkite-agent artifact download.
  4. If it can't run locally (internal infrastructure, secrets, cross-agent parallelism, artifacts from earlier steps): push a debug branch with verbose flags or env | sort, inspect artifacts (buildkite:list_artifacts, JUnit XML, coverage), or fix from logs and artifacts alone. Plugins for artifacts, notifications, or caching don't block local reproduction.

Triggering or rebuilding a build

Some events that feel like they should start a new build don't. GitHub's "ready for review" event, for example, does not trigger a new Buildkite build — only pushes do. If you need a build for the current state without a new commit, don't push an empty commit as a workaround; trigger one directly:

# Start a new build (auto-detects org/pipeline/commit/branch from the current git checkout)
npx bktide@latest build create

# Watch it through to completion
npx bktide@latest build create --watch

# Re-run an existing build with its original commit/branch/message
npx bktide@latest build rebuild <org>/<pipeline>/<build-number>
npx bktide@latest build rebuild <buildkite-build-url>

Flags (--commit, --branch, --message, --env) override git auto-detection; run bktide build create --help for the full list. This is the one write operation bktide supports — it's the direct replacement for bk build create/bk build retry, which the buildkite tool-preference hook blocks in favor of this command.

References

Hooks 1

Sponsors

Details

Marketplace
technicalpickles/pickled-claude-plugins
Source
plugins/buildkite
Category
Community

More from technicalpickles/pickled-claude-plugins

All 26