docker

drone-docker

Drone plugin uses Docker-in-Docker to build and publish Docker images to a container registry. For the usage information and a listing of the available options please take a look at the docs.

Updating Buildkit Version

If you want to update the buildkit version that is bundled with the plugin then update the version in the buildkit/version.json file and also run the following pipeline to upload the assets in the correct place: https://harness0.harness.io/ng/account/l7B_kbSEQD2wjrM7PShm5w/all/orgs/PROD/projects/CI/pipelines/Buildkit_Tarball_Uploader/pipeline-studio?storeType=INLINE

Build

buildkit/version.json is the source of truth for the buildkit version to be used for self hosted. Please update this to use a newer buildkit version

Run the release script for buildkit. Give the argument according to the infra you are compiling for

sh buildkit/release.sh linux/amd64

Build the binaries with the following commands:

export GOOS=linux
export GOARCH=amd64
export CGO_ENABLED=0
export GO111MODULE=on

go build -v -a -tags netgo -o release/linux/amd64/drone-docker ./cmd/drone-docker
go build -v -a -tags netgo -o release/linux/amd64/drone-gcr ./cmd/drone-gcr
go build -v -a -tags netgo -o release/linux/amd64/drone-ecr ./cmd/drone-ecr
go build -v -a -tags netgo -o release/linux/amd64/drone-acr ./cmd/drone-acr
go build -v -a -tags netgo -o release/linux/amd64/drone-heroku ./cmd/drone-heroku

Docker

Build the Docker images with the following commands:

docker build \
  --label org.label-schema.build-date=$(date -u +"%Y-%m-%dT%H:%M:%SZ") \
  --label org.label-schema.vcs-ref=$(git rev-parse --short HEAD) \
  --file docker/docker/Dockerfile.linux.amd64 --tag plugins/docker .

docker build \
  --label org.label-schema.build-date=$(date -u +"%Y-%m-%dT%H:%M:%SZ") \
  --label org.label-schema.vcs-ref=$(git rev-parse --short HEAD) \
  --file docker/gcr/Dockerfile.linux.amd64 --tag plugins/gcr .

docker build \
  --label org.label-schema.build-date=$(date -u +"%Y-%m-%dT%H:%M:%SZ") \
  --label org.label-schema.vcs-ref=$(git rev-parse --short HEAD) \
  --file docker/ecr/Dockerfile.linux.amd64 --tag plugins/ecr .

docker build \
  --label org.label-schema.build-date=$(date -u +"%Y-%m-%dT%H:%M:%SZ") \
  --label org.label-schema.vcs-ref=$(git rev-parse --short HEAD) \
  --file docker/acr/Dockerfile.linux.amd64 --tag plugins/acr .

docker build \
  --label org.label-schema.build-date=$(date -u +"%Y-%m-%dT%H:%M:%SZ") \
  --label org.label-schema.vcs-ref=$(git rev-parse --short HEAD) \
  --file docker/heroku/Dockerfile.linux.amd64 --tag plugins/heroku .

Usage

Notice: Be aware that the Docker plugin currently requires privileged capabilities, otherwise the integrated Docker daemon is not able to start.

Using Docker buildkit Secrets

kind: pipeline
name: default

steps:
- name: build dummy docker file and publish
  image: plugins/docker
  pull: never
  settings:
    repo: tphoney/test
    tags: latest
    secret: id=mysecret,src=secret-file
    username:
      from_secret: docker_username
    password:
      from_secret: docker_password

Using a dockerfile that references the secret-file

# syntax=docker/dockerfile:1.2

FROM alpine

# shows secret from default secret location:
RUN --mount=type=secret,id=mysecret cat /run/secrets/mysecret

and a secret file called secret-file

COOL BANANAS

Running from the CLI

docker run --rm \
  -e PLUGIN_TAG=latest \
  -e PLUGIN_REPO=octocat/hello-world \
  -e DRONE_COMMIT_SHA=d8dbe4d94f15fe89232e0402c6e8a0ddf21af3ab \
  -v $(pwd):$(pwd) \
  -w $(pwd) \
  --privileged \
  plugins/docker --dry-run

Flag Usage

Use PLUGIN_BUILDX_OPTIONS

You can pass all buildx supported flags together using the PLUGIN_BUILDX_OPTIONS environment variable:

envVariables:
  PLUGIN_BUILDX_OPTIONS: "--provenance=false, --platform=linux/amd64"

For options with comma values

If you need to pass options that contain commas in their values (like --output=type=tar,dest=image.tar), use the PLUGIN_BUILDX_OPTIONS_SEMICOLON environment variable with semicolons (;) as separators:

envVariables:
  PLUGIN_BUILDX_OPTIONS_SEMICOLON: "--platform=linux/amd64,linux/arm64;--provenance=false;--output=type=tar,dest=image.tar"

Direct Tar Output (Build + Scan optimization)

When using the Build + Scan + Push flow on Kubernetes (dry-run mode with tar path), the plugin previously performed a costly double serialization: --load (BuildKit to Docker daemon) followed by docker save (daemon to tar file). For large images this could account for 70%+ of the total build time.

The PLUGIN_BUILDX_OUTPUT_FORMAT setting eliminates this by instructing buildx to write the image tar directly in a single pass using --output type=<format>,dest=<path>.

Inputs:

• PLUGIN_BUILDX_OUTPUT_FORMAT: The buildx output format to use for direct tar export. Supported values: docker (Docker archive), oci (OCI layout). When set alongside PLUGIN_TAR_PATH and PLUGIN_DRY_RUN=true, the plugin uses --output instead of --load + docker save.
• PLUGIN_TAR_PATH: Destination path for the image tar file.
• PLUGIN_DRY_RUN: Must be true to activate the tar export flow.

Behavior:

• When PLUGIN_BUILDX_OUTPUT_FORMAT is set: buildx writes directly to the tar path (--output type=<format>,dest=<path>). No Docker daemon load or save occurs.
• When PLUGIN_BUILDX_OUTPUT_FORMAT is not set: the legacy flow (--load + docker save) is used for backward compatibility.
• The docker format produces a tar compatible with docker load -i.
• The oci format produces an OCI image layout (useful for multi-platform images or OCI-native scanners).

Example (Build + Scan + Push on K8s):

envVariables:
  PLUGIN_DRY_RUN: "true"
  PLUGIN_TAR_PATH: /shared/image.tar
  PLUGIN_BUILDX_OUTPUT_FORMAT: docker

This replaces the previous flow of ~69 min (for a 1.6GB image) with a single ~5-10 min write.

Buildx Bake mode (opt-in)

Use Docker Buildx Bake when you have a bake file (HCL/JSON/Compose) and want build orchestration across multiple targets and registries.

Inputs:

• PLUGIN_BAKE_FILE: Path to your bake file. When set, the plugin runs docker buildx bake instead of classic buildx build.
• PLUGIN_BAKE_OPTIONS: Semicolon-delimited extra bake CLI args and/or target names. Example: --progress=plain;web;api or --set=*.platform=linux/amd64.

Behavior:

• Do not include --push or --load in PLUGIN_BAKE_OPTIONS. The plugin adds these implicitly:
  • --push when PLUGIN_DRY_RUN=false (default).
  • --load when PLUGIN_DRY_RUN=true.
• The existing builder-name is passed as --builder to bake if set.
• The plugin does not auto-switch the builder driver in Bake mode. If your bake file uses cache-to (registry exports), set PLUGIN_BUILDER_DRIVER=docker-container explicitly.
• If PLUGIN_METADATA_FILE is set, it is forwarded to bake as --metadata-file.
• Bake mode ignores classic cache envs (PLUGIN_CACHE_FROM / PLUGIN_CACHE_TO / PLUGIN_NO_CACHE). Define cache in the bake file instead.
• Bake mode and Push-only mode (PLUGIN_PUSH_ONLY) are mutually exclusive.
• Classic tar export (PLUGIN_TAR_PATH) is not applied in Bake; define outputs in the bake file.

Examples:

Basic Bake with multi-registry push

envVariables:
  PLUGIN_BAKE_FILE: docker-bake.hcl
  # Either pass a config file path or JSON content for multi-registry auth
  PLUGIN_CONFIG: /path/to/docker-config.json
  # PLUGIN_CONFIG: '{"auths":{"docker.io":{"auth":"..."},"ghcr.io":{"auth":"..."}}}'

Bake with specific targets and progress

envVariables:
  PLUGIN_BAKE_FILE: docker-bake.hcl
  PLUGIN_BAKE_OPTIONS: "--progress=plain;web;api"

Bake with platform override

envVariables:
  PLUGIN_BAKE_FILE: docker-bake.hcl
  PLUGIN_BAKE_OPTIONS: "--set=*.platform=linux/amd64"

Developer Notes

• When updating the base image, you will need to update for each architecture and OS.
• Arm32 base images are no longer being updated.

Release procedure

Run the changelog generator.

docker run -it --rm -v "$(pwd)":/usr/local/src/your-app githubchangeloggenerator/github-changelog-generator -u drone-plugins -p drone-docker -t <secret github token>

You can generate a token by logging into your GitHub account and going to Settings -> Personal access tokens.

Next we tag the PR's with the fixes or enhancements labels. If the PR does not fufil the requirements, do not add a label.

Run the changelog generator again with the future version according to semver.

docker run -it --rm -v "$(pwd)":/usr/local/src/your-app githubchangeloggenerator/github-changelog-generator -u drone-plugins -p drone-docker -t <secret token> --future-release v1.0.0

Create your pull request for the release. Get it merged then tag the release.