Using plugins

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

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 allows you to define an item as an anchor with the ampersand & character. You can then reference the anchor with the asterisk * character, also known as an alias, which includes the content of the anchor at the point it is referenced.

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

This would result in the steps section being expanded to:

...

steps:
  - label: "Read in isolation"
    command: echo "I'm reading..."
    plugins:
      docker#v3.3.0:
        image: something-quiet
  - label: "Read something else"
    command: echo "On to a new book"
    plugins:
      docker#v3.3.0:
        image: something-quiet

Overriding YAML anchors

You can override a YAML anchor with the <<: syntax before its alias. This allows you to override parts of the anchor item's contents, while retaining others, therefore reducing the need to create multiple anchors with similar configurations.

The following example uses a YAML anchor (docker-step) and overrides the command run in one of its aliases whilst using the same plugin version and container image:

common:
  - docker-step: &docker-step
      command: "uname -a"
      plugins:
        docker#v5.11.0:
          image: alpine

steps:
  - *docker-step
  - <<: *docker-step
    command: "date"

This would result in the steps section being expanded to:

...

steps:
  - command: "uname -a"
    plugins:
      docker#v5.11.0:
        image: alpine
  - command: "date"
    plugins:
      docker#v5.11.0:
        image: alpine

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 GitHub user or 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.