buildkite-plugin-dev

Buildkite Plugin Development

You are an expert engineer building production-grade custom Buildkite plugins. A Buildkite plugin is a small git repository the agent clones and runs at specific points in a build via hook scripts. Follow these rules exactly — they reflect how the Buildkite agent actually loads and runs plugins.

Official docs (verify specifics here; some details evolve):

• Writing plugins: https://buildkite.com/docs/pipelines/integrations/plugins/writing
• Using plugins: https://buildkite.com/docs/pipelines/integrations/plugins/using
• Plugin tools/index: https://buildkite.com/docs/pipelines/integrations/plugins
• Agent hooks: https://buildkite.com/docs/agent/v3/hooks

Non-negotiable rules

1. Repo naming. Public plugin repos are conventionally named <thing>-buildkite-plugin (e.g. docker-buildkite-plugin). The agent resolves my-org/docker#v1.0.0 to github.com/my-org/docker-buildkite-plugin.
2. Every plugin has a plugin.yml at the repo root describing its name, author, requirements, and a JSON-Schema configuration block. See reference/plugin-yml-schema.md.
3. Hooks live in hooks/ as executable scripts. Each hook file is named after the lifecycle event (environment, command, pre-exit, ...) with no extension, must be chmod +x, and must start with a shebang. See reference/hooks.md for the full list and execution order.
4. Every hook script starts with:

   #!/bin/bash
   set -euo pipefail
   

   (or #!/usr/bin/env bash). This catches unset vars and pipe failures early.
5. Read config from environment variables, never by parsing YAML. The agent converts the user's plugins: YAML into env vars. See reference/env-var-mapping.md for the exact naming algorithm (uppercasing, non-alphanumeric → _, array indices _0, _1, ...).
6. Always read with a safe default: "${BUILDKITE_PLUGIN_MYPLUGIN_TIMEOUT:-10}". Never assume a var is set.
7. Always quote variable expansions ("$VAR") and use [[ ... ]] for tests. Run shellcheck on every hook.
8. Ship tests. Every plugin needs Bats tests and a CI pipeline. Delegate the test mechanics to the buildkite-plugin-testing skill, but never call a plugin "done" without tests/ and .buildkite/pipeline.yml.