Plugins can be used in pipeline command steps to access a library of commands or perform actions.
On this page:
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. The plugins will be run in the order you list them in the array.
In the example below, the
shellcheck plugin will run, followed by the
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 (e.g.
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.
If you are using Agent hooks as well as plugins, some hook types will run the Agent hooks before the plugin hooks. For a description of each hook type and the order it is run, see the Agent Hooks guide.
Plugins are configured using attributes in your pipeline YAML configuration. 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
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 %n" 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.
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://firstname.lastname@example.org/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
To selectively allow and disallow plugins you can use the agent’s environment hook and the
BUILDKITE_PLUGINS environment variable. See the github.com/buildkite/buildkite-allowed-plugins-hook-example repository for an example implementation.
To disable plugins entirely, set the
no-plugins agent configuration option: