Using plugins
Plugins can be used in pipeline command steps to access a library of commands or perform actions.
Adding a plugin to your pipeline
To add a plugin to a command step, use the plugins
attribute. The plugins
attribute accepts an array, so you can add multiple plugins to the same step.
When multiple plugins are listed in the same step, they will run in the order of the hooks, and within each hook, in the order they were listed in the step.
steps:
- command: yarn install && yarn run test
plugins:
- shellcheck#v1.1.2:
files: scripts/*.sh
- docker#v3.3.0:
image: node
workdir: /app
Always specify a tag or commit (for example, v1.2.3
) to prevent the plugin changing unexpectedly, and to prevent stale checkouts of plugins on your agent machines.
Not all plugins require a command
attribute, for example:
steps:
- plugins:
- docker-login#v2.0.1:
username: xyz
- docker-compose#v3.0.3:
build: app
image-repository: index.docker.io/myorg/myrepo
Although there's no command
attribute in the above example, this is still
considered a command step, so all command attributes are available for use.
It is possible to define multiple hooks of the same type in both a plugins and the agent hooks location. See job lifecycle hooks for the overall order of hooks, and the relative order of invocation for each location.
Configuring plugins
Plugins are configured using attributes on steps in your pipeline YAML definition. While you can't define plugins at a pipeline level, you can use YAML anchors to avoid repeating the plugin code over multiple steps. The simplest plugin is one that accepts no configuration, such as the Library Example plugin:
steps:
- label: ":books:"
plugins:
- library-example#v1.0.0: ~
More commonly, plugins accept various configuration options. For example, the Docker plugin requires the attribute image
, and we have also included the optional workdir
attribute:
steps:
- command: yarn install && yarn run test
plugins:
- docker#v3.3.0:
image: node
workdir: /app
More advanced plugins, such as Docker Compose plugin, are designed to be used multiple times in a pipeline, using the build's meta-data store to share information from one step to the next. This means that you can build a Docker image in the first step of a pipeline and refer to that image in subsequent steps.
steps:
# Prebuild the app image, upload it to a registry for later steps
- label: ":docker: Build"
plugins:
- docker-compose#v3.0.3:
build: app
image-repository: index.docker.io/org/repo
- wait
# Use the app image built above to run concurrent tests
- label: ":docker: Test %spawn"
command: test.sh
parallelism: 25
plugins:
- docker-compose#v3.0.3:
run: app
See each plugin's readme for a list of which options are available.
Using YAML anchors with plugins
YAML anchors enable you to identify an item with an anchor, also known as an alias. You can then reference the anchor when referring to that item.
The following example uses a YAML anchor (docker
) to remove the need to repeat the same plugin configuration on each step:
common:
- docker_plugin: &docker
docker#v3.3.0:
image: something-quiet
steps:
- label: "Read in isolation"
command: echo "I'm reading..."
plugins:
- *docker
- label: "Read something else"
command: echo "On to a new book"
plugins:
- *docker
Plugin sources
There are three main sources of plugins:
- Buildkite-maintained plugins
- Non-Buildkite plugins hosted on GitHub
- Local, private, and non-GitHub plugins
Buildkite-maintained plugins can be found in the Buildkite Plugins GitHub organization. When using these plugins, you can refer to them using only the name of the plugin, for example:
steps:
- command: yarn install && yarn run test
plugins:
# Resolves to https://github.com/buildkite-plugins/docker-buildkite-plugin
- docker#v3.3.0:
image: node
workdir: /app
Non-Buildkite plugins hosted on GitHub require you to include the organization name as well as the plugin name, for example:
steps:
- command: yarn install && yarn run test
plugins:
# Resolves to https://github.com/my-org/docker-buildkite-plugin
- my-org/docker#v3.3.0:
image: node
workdir: /app
Local, private, and non-GitHub plugins can be used by specifying the fully qualified Git URL, for example:
steps:
- command: yarn install && yarn run test
plugins:
- https://bitbucket.com/my-org/my-plugin.git#v1.0.0: ~
- ssh://git@github.com/my-org/my-plugin.git#v1.0.0: ~
- file:///a-local-path/my-plugin.git#v1.0.0: ~
Pinning plugin versions
To avoid a plugin's git tag contents being changed, you can use the commit SHA of the tag, for example using docker-compose#287293c4
in the following example:
steps:
- command: echo 'Hello World'
plugins:
- docker-compose#287293c4:
run: app
Referencing plugins from a specific branch
To test plugins you can reference the branch, for example:
steps:
- command: echo 'Hello World'
plugins:
- docker-compose#feature/add-new-feature:
run: app
Disabling plugins
To selectively allow and disallow plugins see securing your Buildkite Agent.
To disable plugins entirely, set the no-plugins
option.