Docker Extract Buildkite Plugin

A Buildkite plugin to extract a Docker image to the filesystem before running a build step.

Example

This will extract the path /var/www/html from the image example/website:latest:

steps:
  - command: tree output
    plugins:
      - forumone/extract#v0.2.0:
          image: example/website:latest
          from: /var/www/html
          to: output

This shows off all of the options - it extracts the filesystem from a local image (bypassing the normal docker pull process) and enables all logging (verbose + debug):

steps:
  - command: tree output
    plugins:
      - forumone/extract#v0.2.0:
          image: example/website:latest
          pull: false

          from: /var/www/html
          to: output

          verbose: true
          debug: true

As of 0.2.0, this plugin also supports a structured object for configuration. While this is primarily intended to support the docker-compose plugin, it can also be used by anyone wishing to have more explicit configuration. There are no required properties, as this plugin can autogenerate the tag it should use.

steps:
  - command: tree output
    plugins:
      - forumone/extract#v0.2.0:
          from: /var/www/html

          # image name = example.website/user/repo:<pipeline slug>-build-<build number>
          image:
            repository: example.website/user/repo

steps:
  - command: tree output
    plugins:
      - forumone/extract#v0.2.0:
          from: /var/www/html

          # image name = example.website/user/repo:<pipeline slug>-drupal-build-<build number>
          image:
            repository: example.website/user/repo
            service: drupal

steps:
  - command: tree output
    plugins:
      - forumone/extract#v0.2.0:
          from: /var/www/html

          # image name = example.website/user/repo:latest
          image:
            repository: example.website
            tag: latest

Options

image (optional)

This can be:

1. A string specifying the full Docker tag to use, or
2. An object with options corresponding to configuration that can be used to mimic the format of the docker-compose plugin.

The image object options

repository (optional)

The repository to push to. If it isn't present in the configuration, it can be automatically determined in a few ways:

1. The environment variable BUILDKITE_PLUGIN_EXTRACT_IMAGE_REPOSITORY
2. The environment variable BUILDKITE_PLUGIN_COMPOSE_IMAGE_REPOSITORY, consistent with the image-repository setting of the docker-compose plugin.
3. The default value '', meaning that the image is either an existing image (if pull: false) or a Docker Library image (if pull: true).

service (optional, conflicts with tag)

The service name to use as part of the tag. This value is needed to mimic the docker-compose plugin's format: if you specified a configuration like the below, then you'll need to set service: drupal in this plugin's configuration.

Due to a quirk in how Buildkite serializes a plugin's configuration, you can specify this value as image-service: instead of nesting service: underneath image:.

tag (optional, conflicts with service)

This overrides the generated tag with a specific one. Useful to match a format generated by other tools or to extract from third-party images.

tag (optional)

pull (optional)

A boolean indicating if the named image should be pulled before extraction. Defaults to true; set to false when testing locally or if the image is built as part of the same pipeline step.

from

A string naming the path to be extracted from the image. This corresponds to the path where you've put your data - /var/www/html for most PHP-based images, for example.

to (optional)

A string naming the path on disk to extract to. When left off, defaults to . (i.e., the root of the checkout).

verbose (optional)

Enables some extra logging messages.

debug (optional)

Enables debug-level output. Only needed if you suspect a bug in the plugin.