- version
- 1.1.4
- GitHub stars
- 13
Install
/plugin install buildkite@pickled-claude-pluginsRun it inside Claude Code after adding the marketplace with /plugin marketplace add technicalpickles/pickled-claude-plugins.
Contents
Discovered from sourceSkills 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:
- Identify plugins - Note all
plugins:entries in the step - Determine source:
- Default org
buildkite-pluginsif no org specified - Parse explicit org from
{org}/{plugin}#versionformat
- Default org
- 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
- 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?"
- Check references/plugins/index.md for common plugins by category
- Fetch Buildkite directory:
https://buildkite.com/resources/plugins/ - 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.ymlreferences a Docker image containing "buildkite-builder".buildkite/pipeline.rbor.buildkite/pipelines/*/pipeline.rbexists
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 stepsdynamic-pipelines.md- Generating steps programmaticallydependencies.md- Using depends_on, parallel stepsenvironment-variables.md- Setting and using env varsconditionals.md- if/branches for conditional executionartifacts.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 executionplugins/docker-compose.md- Multi-container environmentsplugins/artifacts.md- Artifact upload/downloadplugins/ecr.md- AWS ECR authenticationplugins/cache.md- Dependency caching
buildkite-builder references (when detected):
buildkite-builder/index.md- Overview and when to usebuildkite-builder/dsl-syntax.md- Core DSL step typesbuildkite-builder/step-attributes.md- Common attributesbuildkite-builder/templates.md- Reusable step templatesbuildkite-builder/extensions.md- Custom DSL and extensionsbuildkite-builder/conditionals.md- Conditional step generationbuildkite-builder/dependencies.md- Step dependenciesbuildkite-builder/artifacts.md- Artifact handlingbuildkite-builder/plugins.md- Plugin usage in DSLbuildkite-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:
- Scan for ENV variable usage
- Generate Docker validation command with placeholders
- 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:
- Read pipeline.rb - Understand the Ruby DSL
- Run Docker command - Generate YAML to see actual output
- Compare output - Expected vs actual YAML
- Reference both docs - buildkite-builder DSL AND Buildkite YAML docs
- Identify issue - Where Ruby DSL produces unexpected YAML
- 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:
- Reference dynamic-pipelines.md for current patterns
- Use Buildkite SDK if available (see dynamic-pipelines.md)
- Validate generated output with --dry-run
- 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:
- Verify step structure in references/step-types.md
- Validate dependencies in references/dependencies.md
- 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.
-
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 --helpfor options,bktide primefor 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} -
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). -
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 withdetail_level: "summary"and filter withjob_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(orFAILED) AND non-zeroexit_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 fromget_buildAPI responses. - Empty logs: The job may not have started yet. Check the job's
statefield 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
- 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. - Find the environment: vars printed in the log,
env:blocks in.buildkite/pipeline.yml(or the buildkite-builder DSL), and Buildkite defaults likeCI=true(references/buildkite-environment-variables.md). - Translate: run the command directly first; if it ran in Docker,
docker-compose run [-e CI=true ...] <service> <command>. Drop CI-only flags (--parallel 4to 1,--format buildkiteto progress) and skipbuildkite-agent artifact download. - 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
- references/troubleshooting.md: common errors and a decision tree for when stuck
- references/url-parsing.md: Buildkite URLs, step IDs vs job UUIDs
- scripts/parse-buildkite-url.js, scripts/get-build-logs.js: URL parsing and label-to-UUID log retrieval; run with
--help
Hooks 1
Sponsors
Details
- Marketplace
- technicalpickles/pickled-claude-plugins
- Source
- plugins/buildkite
- Category
- Community
More from technicalpickles/pickled-claude-plugins
All 26- ci-cd-toolsv1.2.2
- come-onv0.2.1
- cqv0.3.1
- dev-toolsv1.5.0
- gitv3.6.0
- github-actionsv0.1.1
- hkv0.2.0
- inflight-artifactv0.5.0
- mcpproxyv1.0.2
- petri-dishv0.1.0
- pickle-modev0.3.0
- sandbox-advisorv0.3.0
- second-brainv2.2.0
- stay-on-targetv1.0.1
- stay-principledv0.1.1
- tailscalev0.5.0
- taskwarriorv1.4.0
- tool-routingv1.4.0
- wait-for-itv0.2.2
- woodpeckerv0.4.0
- working-in-monoreposv1.0.4
- writing-toolsv0.3.0
- actually-lspv0.7.1
- agent-metav3.4.1
