Docker Cache Buildkite Plugin

A Buildkite plugin for caching Docker images across builds using various registry providers (ECR, GAR, and Buildkite Packages currently supported).

This plugin speeds up your Docker builds by caching images between pipeline runs. Instead of rebuilding the same Docker image every time, it stores built images in ECR, Google Artifact Registry, or Buildkite Packages and reuses them when nothing has changed.

The plugin will check if a cached version of your image already exists. If it does, it pulls that instead of rebuilding. If not, it builds the image and saves it for next time. It automatically creates the necessary repositories in your registry if they don't exist (ECR and GAR only - Buildkite Packages registries are managed through the UI).

Cache keys are generated based on your Dockerfile content and build context, so the cache automatically invalidates when you make changes to your code or build configuration.

Also see the Docker Buildkite Plugin for running pipeline steps in Docker containers.

Example

ECR Provider

The following pipeline will cache Docker builds in Amazon ECR.

steps:
  - label: "🐳 Build with ECR cache"
    command: "echo 'Building with cache'"
    plugins:
      - docker-cache#v1.0.0:
          provider: ecr
          image: my-app
          ecr:
            region: us-east-1
            account-id: "123456789012"

GAR Provider

The following pipeline will cache Docker builds in Google Artifact Registry:

steps:
  - label: "🐳 Build with GAR cache"
    command: "echo 'Building with cache'"
    plugins:
      - docker-cache#v1.0.0:
          provider: gar
          image: my-app
          gar:
            project: my-gcp-project
            region: us

Buildkite Packages Provider

The following pipeline will cache Docker builds in Buildkite Packages Container Registry:

steps:
  - label: "🐳 Build with Buildkite Packages cache"
    command: "echo 'Building with cache'"
    plugins:
      - docker-cache#v1.0.0:
          provider: buildkite
          image: my-app
          buildkite:
            org-slug: my-org

With OIDC Authentication

steps:
  - label: "🐳 Build with Buildkite Packages cache (OIDC)"
    command: "echo 'Building with cache'"
    plugins:
      - docker-cache#v1.0.0:
          provider: buildkite
          image: my-app
          buildkite:
            org-slug: my-org
            auth-method: oidc

Cache Strategies

You can control how the cache is used with different strategies:

Artifact Strategy

Pulls the complete cached image if available, builds from scratch if not:

steps:
  - label: "🐳 Artifact strategy"
    plugins:
      - docker-cache#v1.0.0:
          provider: ecr
          image: my-app
          strategy: artifact
          ecr:
            region: us-east-1
            account-id: "123456789012"

Build Strategy

Uses layer caching during the build process:

steps:
  - label: "🐳 Build strategy"
    plugins:
      - docker-cache#v1.0.0:
          provider: ecr
          image: my-app
          strategy: build
          ecr:
            region: us-east-1
            account-id: "123456789012"

Hybrid Strategy

Tries artifact strategy first, falls back to build strategy if pull fails:

steps:
  - label: "🐳 Hybrid strategy"
    plugins:
      - docker-cache#v1.0.0:
          provider: ecr
          image: my-app
          strategy: hybrid
          ecr:
            region: us-east-1
            account-id: "123456789012"

Multi-stage Builds

For multi-stage Dockerfiles, you can specify the target stage:

steps:
  - label: "🐳 Multi-stage build"
    plugins:
      - docker-cache#v1.0.0:
          provider: ecr
          image: my-app
          target: production
          ecr:
            region: us-east-1
            account-id: "123456789012"

Build Arguments

You can pass build arguments to Docker:

steps:
  - label: "🐳 Build with args"
    plugins:
      - docker-cache#v1.0.0:
          provider: ecr
          image: my-app
          build-args:
            - NODE_ENV=production
            - API_URL=https://api.example.com
          ecr:
            region: us-east-1
            account-id: "123456789012"

Configuration

These are all the options available to configure this plugin's behaviour.

Required

provider (string)

Which registry provider to use for caching. Supported values: ecr, gar, buildkite.

image (string)

Name of your Docker image.

Example: my-app

Optional

strategy (string, default: hybrid)

How to use the cache:

• artifact: Pull complete cached image if available, build from scratch if not
• build: Use layer caching during build process
• hybrid: Try artifact strategy first, fall back to build strategy if pull fails

dockerfile (string, default: Dockerfile)

Path to your Dockerfile.

dockerfile-inline (string)

Inline Dockerfile content instead of reading from a file.

context (string, default: .)

Docker build context path.

target (string)

Target stage for multi-stage builds.

build-args (array)

Build arguments to pass to Docker.

Example: ["NODE_ENV=production", "VERSION=1.0.0"]

additional-build-args (string)

Additional docker build arguments as a single string.

Example: "--network=host --build-arg CUSTOM_ARG=value"

secrets (array)

Build secrets to pass to Docker (requires BuildKit).

Example: ["id=mysecret,src=/local/secret", "id=mypassword"]

cache-from (array)

Additional cache sources for Docker build.

Example: ["my-base-image:latest"]

skip-pull-from-cache (boolean, default: false)

Skip pulling from cache (useful for testing).

save (boolean, default: true)

Whether to save cache after build.

restore (boolean, default: true)

Whether to restore cache before build.

max-age-days (number, default: 30)

Maximum age in days for cached images.

cache-key (string or array)

Custom cache key. If not provided, automatically generated from Dockerfile content and build context.

Example: ["my-key", "v1.0"] or "custom-key"

export-env-variable (string, default: BUILDKITE_PLUGIN_DOCKER_IMAGE)

Environment variable name for exporting the final image reference.

verbose (boolean, default: false)

Enable verbose logging.

tag (string)

Custom tag for the cached image. If not provided, generated from git commit or pipeline context.

ECR Provider Options

When using provider: ecr, these options are available:

ecr.region (string)

AWS region for ECR registry. If not provided, will be auto-detected from AWS configuration.

Example: us-east-1

ecr.account-id (string)

AWS account ID (12 digits). If not provided, will be auto-detected from AWS credentials.

Example: 123456789012

ecr.registry-url (string)

Custom ECR registry URL. If not provided, will be constructed from account ID and region.

Example: 123456789012.dkr.ecr.us-east-1.amazonaws.com

GAR Provider Options

Note: Authentication is handled by the gcloud CLI. Ensure your Buildkite agent has authenticated with Google Cloud before running this plugin (e.g., using a service account key or Workload Identity Federation).

When using provider: gar, these options are available:

gar.project (string, required)

Google Cloud project ID.

Example: my-gcp-project

gar.region (string, default: us)

GAR region.

Valid values: us, europe, asia, or specific regional endpoints like us-central1-docker.pkg.dev

Example: us

gar.repository (string)

Artifact Registry repository name. If not provided, defaults to the image name.

Example: docker (for repository name, results in full path like us-docker.pkg.dev/project/docker/image)

Buildkite Packages Provider Options

Note: Authentication requires either a Buildkite API token with Read Packages and Write Packages scopes, or OIDC authentication using buildkite-agent (available in Buildkite pipeline jobs).

When using provider: buildkite, these options are available:

buildkite.org-slug (string)

Buildkite organization slug. If omitted, it will use the BUILDKITE_ORGANIZATION_SLUG environment variable.

Example: my-org

buildkite.registry-slug (string)

Container registry slug. If omitted, it defaults to the image name.

Example: docker-images

buildkite.auth-method (string, default: api-token)

Authentication method to use. Supported values: api-token, oidc.

• api-token: Uses the api-token parameter or falls back to BUILDKITE_API_TOKEN environment variable
• oidc: Uses buildkite-agent oidc request-token command (available in pipeline jobs)

buildkite.api-token (string)

Buildkite API token with Read Packages and Write Packages scopes. Required when auth-method is api-token. Can also be provided via the BUILDKITE_API_TOKEN environment variable for backward compatibility.

Authentication

ECR Authentication

The plugin handles ECR authentication automatically using your existing AWS credentials. Make sure your build environment has AWS credentials configured through:

• IAM roles (recommended for EC2/ECS)
• AWS credentials file
• Environment variables (AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY)

Required permissions:

• sts:GetCallerIdentity
• ecr:GetAuthorizationToken
• ecr:DescribeRepositories
• ecr:CreateRepository
• ecr:BatchGetImage
• ecr:GetDownloadUrlForLayer
• ecr:BatchCheckLayerAvailability
• ecr:PutImage
• ecr:InitiateLayerUpload
• ecr:UploadLayerPart
• ecr:CompleteLayerUpload

GAR Authentication

The plugin uses gcloud for GAR authentication with your existing Google Cloud credentials. Make sure your build environment has Google Cloud credentials configured through:

• Service account keys
• Workload Identity (recommended for GKE)
• Application Default Credentials

Required permissions:

• artifactregistry.repositories.get
• artifactregistry.repositories.create
• artifactregistry.docker.images.get
• artifactregistry.docker.images.push
• artifactregistry.docker.images.pull

Buildkite Packages Authentication

The plugin supports two authentication methods for Buildkite Packages:

API Token Authentication (Default)

Uses a Buildkite API token with Read Packages and Write Packages scopes:

plugins:
  - docker-cache#v1.0.0:
      provider: buildkite
      image: my-app
      buildkite:
        org-slug: my-org
        api-token: $BUILDKITE_API_TOKEN

Or set the BUILDKITE_API_TOKEN environment variable in your build environment.

Required token scopes:

• read_packages - To pull cached images
• write_packages - To push new cache images

OIDC Authentication

Uses buildkite-agent OIDC tokens for passwordless authentication:

plugins:
  - docker-cache#v1.0.0:
      provider: buildkite
      image: my-app
      buildkite:
        org-slug: my-org
        auth-method: oidc

OIDC authentication requires:

• buildkite-agent v3.38.0 or later
• Proper OIDC policy configuration in your Buildkite organization
• Pipeline access to the target registry

Cache Key Generation

Cache keys are automatically generated from:

• Dockerfile content hash (primary)
• Build context hash (if different from Dockerfile location)
• Build arguments
• Target stage (for multi-stage builds)

This ensures the cache is invalidated whenever anything that affects the build changes.

Compatibility

Elastic Stack	Agent Stack K8s	Hosted (Mac)	Hosted (Linux)	Notes
✅	✅	❌	✅	ECR – Requires awscli GAR – Requires gcloud Hosted (Mac) – Docker engine not available

• ✅ Fully supported (all combinations of attributes have been tested to pass)
• ⚠️ Partially supported (some combinations cause errors/issues)
• ❌ Not supported

Developing

To run tests, you can use the docker Plugin Tester:

docker run --rm -ti -v "${PWD}":/plugin buildkite/plugin-tester:latest

License

MIT (see LICENSE)