{"id":34991248,"url":"https://github.com/buildkite-plugins/docker-cache-buildkite-plugin","last_synced_at":"2026-01-26T21:20:11.682Z","repository":{"id":306911519,"uuid":"1020282378","full_name":"buildkite-plugins/docker-cache-buildkite-plugin","owner":"buildkite-plugins","description":"🐳 🚀 Speed up Docker builds with cloud registry caching","archived":false,"fork":false,"pushed_at":"2026-01-22T22:18:56.000Z","size":65,"stargazers_count":2,"open_issues_count":4,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-01-23T10:55:43.911Z","etag":null,"topics":["aws","buildkite-plugin","docker","ecr","gar","gcp","gcr"],"latest_commit_sha":null,"homepage":"","language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/buildkite-plugins.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-07-15T16:11:47.000Z","updated_at":"2026-01-08T05:34:32.000Z","dependencies_parsed_at":"2025-07-28T12:15:08.072Z","dependency_job_id":"60b73a9a-5623-4e4b-a95f-c586ded58629","html_url":"https://github.com/buildkite-plugins/docker-cache-buildkite-plugin","commit_stats":null,"previous_names":["buildkite-plugins/docker-cache-buildkite-plugin"],"tags_count":1,"template":false,"template_full_name":"buildkite-plugins/template-buildkite-plugin","purl":"pkg:github/buildkite-plugins/docker-cache-buildkite-plugin","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/buildkite-plugins%2Fdocker-cache-buildkite-plugin","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/buildkite-plugins%2Fdocker-cache-buildkite-plugin/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/buildkite-plugins%2Fdocker-cache-buildkite-plugin/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/buildkite-plugins%2Fdocker-cache-buildkite-plugin/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/buildkite-plugins","download_url":"https://codeload.github.com/buildkite-plugins/docker-cache-buildkite-plugin/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/buildkite-plugins%2Fdocker-cache-buildkite-plugin/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28788368,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-26T21:13:08.818Z","status":"ssl_error","status_checked_at":"2026-01-26T21:13:08.448Z","response_time":59,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["aws","buildkite-plugin","docker","ecr","gar","gcp","gcr"],"created_at":"2025-12-27T01:54:42.941Z","updated_at":"2026-01-26T21:20:11.668Z","avatar_url":"https://github.com/buildkite-plugins.png","language":"Shell","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Docker Cache Buildkite Plugin [![Build status](https://badge.buildkite.com/a3851ab6b8e918f7a29d1d43fd8a410308fd5a50455b8a4ab3.svg)](https://buildkite.com/buildkite/plugins-docker-cache)\n\nA [Buildkite plugin](https://buildkite.com/docs/agent/v3/plugins) for caching [Docker](https://docker.com) images across builds using various registry providers (ECR, GAR, ACR, Buildkite Packages, and Artifactory Docker Registry currently supported).\n\nThis 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, Azure Container Registry, Buildkite Packages, or Artifactory Docker Registry and reuses them when nothing has changed.\n\nThe 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, GAR, and ACR - Buildkite Packages registries are managed through the UI).\n\nCache 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.\n\nAlso see the [Docker Buildkite Plugin](https://github.com/buildkite-plugins/docker-buildkite-plugin) for running pipeline steps in Docker containers.\n\n## Example\n\n### ECR Provider\n\nThe following pipeline will cache Docker builds in Amazon ECR.\n\n```yaml\nsteps:\n  - label: \"🐳 Build with ECR cache\"\n    command: \"echo 'Building with cache'\"\n    plugins:\n      - docker-cache#v1.1.0:\n          provider: ecr\n          image: my-app\n          ecr:\n            region: us-east-1\n            account-id: \"123456789012\"\n```\n\n### GAR Provider\n\nThe following pipeline will cache Docker builds in Google Artifact Registry:\n\n```yaml\nsteps:\n  - label: \"🐳 Build with GAR cache\"\n    command: \"echo 'Building with cache'\"\n    plugins:\n      - docker-cache#v1.1.0:\n          provider: gar\n          image: my-app\n          gar:\n            project: my-gcp-project\n            region: us\n```\n\n### Buildkite Packages Provider\n\nThe following pipeline will cache Docker builds in Buildkite Packages Container Registry:\n\n```yaml\nsteps:\n  - label: \"🐳 Build with Buildkite Packages cache\"\n    command: \"echo 'Building with cache'\"\n    plugins:\n      - docker-cache#v1.1.0:\n          provider: buildkite\n          image: my-app\n          buildkite:\n            org-slug: my-org\n```\n\n#### With OIDC Authentication\n\n```yaml\nsteps:\n  - label: \"🐳 Build with Buildkite Packages cache (OIDC)\"\n    command: \"echo 'Building with cache'\"\n    plugins:\n      - docker-cache#v1.1.0:\n          provider: buildkite\n          image: my-app\n          buildkite:\n            org-slug: my-org\n            auth-method: oidc\n```\n\n### Artifactory Docker Registry Provider\n\nThe following pipeline will cache Docker builds in Artifactory Docker Registry:\n\n```yaml\nsteps:\n  - label: \"🐳 Build with Artifactory cache\"\n    command: \"echo 'Building with cache'\"\n    plugins:\n      - docker-cache#v1.1.0:\n          provider: artifactory\n          image: my-app\n          artifactory:\n            registry-url: myjfroginstance.jfrog.io\n            username: me@example.com\n            identity-token: $ARTIFACTORY_IDENTITY_TOKEN\n```\n\n### Azure Container Registry (ACR) Provider\n\nThe following pipeline will cache Docker builds in Azure Container Registry:\n\n```yaml\nsteps:\n  - label: \"🐳 Build with ACR cache\"\n    command: \"echo 'Building with cache'\"\n    plugins:\n      - docker-cache#v1.1.0:\n          provider: acr\n          image: my-app\n          acr:\n            registry-name: myregistry\n```\n\n### Cache Strategies\n\nYou can control how the cache is used with different strategies:\n\n#### Artifact Strategy\n\nPulls the complete cached image if available, builds from scratch if not:\n\n```yaml\nsteps:\n  - label: \"🐳 Artifact strategy\"\n    plugins:\n      - docker-cache#v1.1.0:\n          provider: ecr\n          image: my-app\n          strategy: artifact\n          ecr:\n            region: us-east-1\n            account-id: \"123456789012\"\n```\n\n#### Build Strategy\n\nUses layer caching during the build process:\n\n```yaml\nsteps:\n  - label: \"🐳 Build strategy\"\n    plugins:\n      - docker-cache#v1.1.0:\n          provider: ecr\n          image: my-app\n          strategy: build\n          ecr:\n            region: us-east-1\n            account-id: \"123456789012\"\n```\n\n#### Hybrid Strategy\n\nTries artifact strategy first, falls back to build strategy if pull fails:\n\n```yaml\nsteps:\n  - label: \"🐳 Hybrid strategy\"\n    plugins:\n      - docker-cache#v1.1.0:\n          provider: ecr\n          image: my-app\n          strategy: hybrid\n          ecr:\n            region: us-east-1\n            account-id: \"123456789012\"\n```\n\n### Multi-stage Builds\n\nFor multi-stage Dockerfiles, you can specify the target stage:\n\n```yaml\nsteps:\n  - label: \"🐳 Multi-stage build\"\n    plugins:\n      - docker-cache#v1.1.0:\n          provider: ecr\n          image: my-app\n          target: production\n          ecr:\n            region: us-east-1\n            account-id: \"123456789012\"\n```\n\n### Build Arguments\n\nYou can pass build arguments to Docker:\n\n```yaml\nsteps:\n  - label: \"🐳 Build with args\"\n    plugins:\n      - docker-cache#v1.1.0:\n          provider: ecr\n          image: my-app\n          build-args:\n            - NODE_ENV=production\n            - API_URL=https://api.example.com\n          ecr:\n            region: us-east-1\n            account-id: \"123456789012\"\n```\n\n## Configuration\n\nThese are all the options available to configure this plugin's behaviour.\n\n### Required\n\n#### `provider` (string)\n\nWhich registry provider to use for caching. Supported values: `ecr`, `gar`, `acr`, `buildkite`, `artifactory`.\n\n#### `image` (string)\n\nName of your Docker image.\n\nExample: `my-app`\n\n### Optional\n\n#### `strategy` (string, default: `hybrid`)\n\nHow to use the cache:\n\n- `artifact`: Pull complete cached image if available, build from scratch if not\n- `build`: Use layer caching during build process\n- `hybrid`: Try artifact strategy first, fall back to build strategy if pull fails\n\n#### `dockerfile` (string, default: `Dockerfile`)\n\nPath to your Dockerfile.\n\n#### `dockerfile-inline` (string)\n\nInline Dockerfile content instead of reading from a file.\n\n#### `context` (string, default: `.`)\n\nDocker build context path.\n\n#### `target` (string)\n\nTarget stage for multi-stage builds.\n\n#### `build-args` (array)\n\nBuild arguments to pass to Docker.\n\nExample: `[\"NODE_ENV=production\", \"VERSION=1.0.0\"]`\n\n#### `additional-build-args` (string)\n\nAdditional docker build arguments as a single string.\n\nExample: `\"--network=host --build-arg CUSTOM_ARG=value\"`\n\n#### `secrets` (array)\n\nBuild secrets to pass to Docker (requires BuildKit).\n\nExample: `[\"id=mysecret,src=/local/secret\", \"id=mypassword\"]`\n\n#### `cache-from` (array)\n\nAdditional cache sources for Docker build.\n\nExample: `[\"my-base-image:latest\"]`\n\n#### `skip-pull-from-cache` (boolean, default: `false`)\n\nSkip pulling from cache (useful for testing).\n\n#### `save` (boolean, default: `true`)\n\nWhether to save cache after build.\n\n#### `restore` (boolean, default: `true`)\n\nWhether to restore cache before build.\n\n#### `max-age-days` (number, default: `30`)\n\nMaximum age in days for cached images.\n\n#### `cache-key` (string or array)\n\nCustom cache key. If not provided, automatically generated from Dockerfile content and build context.\n\nExample: `[\"my-key\", \"v1.0\"]` or `\"custom-key\"`\n\n#### `export-env-variable` (string, default: `BUILDKITE_PLUGIN_DOCKER_IMAGE`)\n\nEnvironment variable name for exporting the final image reference.\n\n#### `verbose` (boolean, default: `false`)\n\nEnable verbose logging.\n\n#### `fallback-tag` (string, default: `latest`)\n\nTag used for layer caching \"fallback\" when no exact cache match exists. The plugin looks for an image with this tag to use for Docker layer caching, improving build performance even without an exact cache hit. Useful for registries with immutable tags where `:latest` cannot be overwritten.\n\nUsing a static tag:\n\n```yaml\nsteps:\n  - plugins:\n      - docker-cache#v1.1.0:\n          provider: ecr\n          image: my-app\n          fallback-tag: cache-main\n```\n\nUsing a tag containing the commit SHA:\n\n```yaml\nsteps:\n  - plugins:\n      - docker-cache#v1.1.0:\n          provider: acr\n          image: my-app\n          fallback-tag: cache-${BUILDKITE_COMMIT:0:7}\n```\n\nUsing the build number as part of the tag:\n\n```yaml\nsteps:\n  - plugins:\n      - docker-cache#v1.1.0:\n          provider: gar\n          image: my-app\n          fallback-tag: build-${BUILDKITE_BUILD_NUMBER}\n```\n\n#### `tag` (string)\n\nCustom tag for the cached image. If not provided, generated from git commit or pipeline context.\n\n### ECR Provider Options\n\nWhen using `provider: ecr`, these options are available:\n\n#### `ecr.region` (string)\n\nAWS region for ECR registry. If not provided, will be auto-detected from AWS configuration.\n\nExample: `us-east-1`\n\n#### `ecr.account-id` (string)\n\nAWS account ID (12 digits). If not provided, will be auto-detected from AWS credentials.\n\nExample: `123456789012`\n\n#### `ecr.registry-url` (string)\n\nCustom ECR registry URL. If not provided, will be constructed from account ID and region.\n\nExample: `123456789012.dkr.ecr.us-east-1.amazonaws.com`\n\n### GAR Provider Options\n\n**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).\n\nWhen using `provider: gar`, these options are available:\n\n#### `gar.project` (string, required)\n\nGoogle Cloud project ID.\n\nExample: `my-gcp-project`\n\n#### `gar.region` (string, default: `us`)\n\nGAR region.\n\nValid values: `us`, `europe`, `asia`, or specific regional endpoints like `us-central1-docker.pkg.dev`\n\nExample: `us`\n\n#### `gar.repository` (string)\n\nArtifact Registry repository name. If not provided, defaults to the image name.\n\nExample: `docker` (for repository name, results in full path like `us-docker.pkg.dev/project/docker/image`)\n\n### Buildkite Packages Provider Options\n\n**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).\n\nWhen using `provider: buildkite`, these options are available:\n\n#### `buildkite.org-slug` (string)\n\nBuildkite organization slug. If omitted, it will use the `BUILDKITE_ORGANIZATION_SLUG` environment variable.\n\nExample: `my-org`\n\n#### `buildkite.registry-slug` (string)\n\nContainer registry slug. If omitted, it defaults to the image name.\n\nExample: `docker-images`\n\n#### `buildkite.auth-method` (string, default: `api-token`)\n\nAuthentication method to use. Supported values: `api-token`, `oidc`.\n\n- `api-token`: Uses the `api-token` parameter or falls back to `BUILDKITE_API_TOKEN` environment variable\n- `oidc`: Uses `buildkite-agent oidc request-token` command (available in pipeline jobs)\n\n#### `buildkite.api-token` (string)\n\nBuildkite 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.\n\n### Artifactory Provider Options\n\n**Note:** Authentication requires a username (typically email) and identity token from your Artifactory instance.\n\nWhen using `provider: artifactory`, these options are available:\n\n#### `artifactory.registry-url` (string, required)\n\nThe Artifactory registry URL (e.g., `myjfroginstance.jfrog.io`). Do not include the protocol (`https://`).\n\n#### `artifactory.username` (string, required)\n\nThe username for Artifactory authentication, typically your email address.\n\n#### `artifactory.identity-token` (string, required)\n\nThe Artifactory identity token for authentication. Can reference an environment variable using `$VARIABLE_NAME` syntax.\n\n#### `artifactory.repository` (string)\n\nArtifactory repository name. If omitted, defaults to the image name.\n\n### ACR Provider Options\n\n**Note:** Authentication is handled by the Azure CLI (`az`). Ensure your Buildkite agent has authenticated with Azure before running this plugin. The authentication token has a 3-hour TTL, which is typically sufficient for CI/CD builds.\n\nWhen using `provider: acr`, these options are available:\n\n#### `acr.registry-name` (string, required)\n\nThe ACR registry name (not the full URL). The plugin will construct the full registry URL as `{registry-name}.azurecr.io`.\n\nThe registry name must be 5-50 alphanumeric characters and start with a letter.\n\nExample: `myregistry` (results in `myregistry.azurecr.io`)\n\n#### `acr.repository` (string)\n\nACR repository name. If omitted, defaults to the image name.\n\nThis allows you to organize cache images in a specific repository namespace.\n\nExample: `docker-cache` (for repository name, results in full path like `myregistry.azurecr.io/docker-cache/image`)\n\n## Authentication\n\n### ECR Authentication\n\nThe plugin handles ECR authentication automatically using your existing AWS credentials. Make sure your build environment has AWS credentials configured through:\n\n- IAM roles (recommended for EC2/ECS)\n- AWS credentials file\n- Environment variables (`AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`)\n\nRequired permissions:\n\n- `sts:GetCallerIdentity`\n- `ecr:GetAuthorizationToken`\n- `ecr:DescribeRepositories`\n- `ecr:CreateRepository`\n- `ecr:BatchGetImage`\n- `ecr:GetDownloadUrlForLayer`\n- `ecr:BatchCheckLayerAvailability`\n- `ecr:PutImage`\n- `ecr:InitiateLayerUpload`\n- `ecr:UploadLayerPart`\n- `ecr:CompleteLayerUpload`\n\n### GAR Authentication\n\nThe plugin uses gcloud for GAR authentication with your existing Google Cloud credentials. Make sure your build environment has Google Cloud credentials configured through:\n\n- Service account keys\n- Workload Identity (recommended for GKE)\n- Application Default Credentials\n\nRequired permissions:\n\n- `artifactregistry.repositories.get`\n- `artifactregistry.repositories.create`\n- `artifactregistry.docker.images.get`\n- `artifactregistry.docker.images.push`\n- `artifactregistry.docker.images.pull`\n\n### Buildkite Packages Authentication\n\nThe plugin supports two authentication methods for Buildkite Packages:\n\n#### API Token Authentication (Default)\n\nUses a Buildkite API token with Read Packages and Write Packages scopes:\n\n```yaml\nplugins:\n  - docker-cache#v1.1.0:\n      provider: buildkite\n      image: my-app\n      buildkite:\n        org-slug: my-org\n        api-token: $BUILDKITE_API_TOKEN\n```\n\nOr set the `BUILDKITE_API_TOKEN` environment variable in your build environment.\n\nRequired token scopes:\n- `read_packages` - To pull cached images\n- `write_packages` - To push new cache images\n\n#### OIDC Authentication\n\nUses buildkite-agent OIDC tokens for passwordless authentication:\n\n```yaml\nplugins:\n  - docker-cache#v1.1.0:\n      provider: buildkite\n      image: my-app\n      buildkite:\n        org-slug: my-org\n        auth-method: oidc\n```\n\nOIDC authentication requires:\n- buildkite-agent v3.38.0 or later\n- Proper OIDC policy configuration in your Buildkite organization\n- Pipeline access to the target registry\n\n### ACR Authentication\n\nThe plugin uses the Azure CLI (`az`) for ACR authentication. Ensure your build environment has Azure credentials configured using one of the following methods:\n\n- Service Principal credentials\n- Managed Identity (recommended for Azure VMs/AKS)\n- Azure CLI login (`az login`)\n\nThe plugin automatically runs `az acr login --name {registry-name}` to authenticate with your ACR registry.\n\nRequired Azure roles:\n- `AcrPull` - To pull cached images from the registry\n- `AcrPush` - To push new cache images to the registry\n\n**Token Expiration:** ACR authentication tokens have a 3-hour TTL. This is typically sufficient for CI/CD builds. For longer-running builds, consider using Managed Identity which automatically refreshes tokens.\n\n**Repository Auto-Creation:** Unlike some other registries, ACR automatically creates repositories on first push. No explicit repository creation is required.\n\n## Cache Key Generation\n\nCache keys are automatically generated from:\n\n- Dockerfile content hash (primary)\n- Build context hash (if different from Dockerfile location)\n- Build arguments\n- Target stage (for multi-stage builds)\n\nThis ensures the cache is invalidated whenever anything that affects the build changes.\n\n## Compatibility\n\n| Elastic Stack | Agent Stack K8s | Hosted (Mac) | Hosted (Linux) | Notes |\n| :-----------: | :-------------: | :----------: | :------------: |:---- |\n| ✅ |  ✅ | ❌ | ✅ | **ECR** – Requires `awscli`\u003cbr/\u003e**GAR** – Requires `gcloud`\u003cbr/\u003e**ACR** – Requires `az` (Azure CLI)\u003cbr/\u003e**Buildkite Packages** – Requires `docker`\u003cbr/\u003e**Artifactory** – Requires `docker`\u003cbr/\u003e**Hosted (Mac)** – Docker engine not available |\n\n- ✅ Fully supported (all combinations of attributes have been tested to pass)\n- ⚠️ Partially supported (some combinations cause errors/issues)\n- ❌ Not supported\n\n## Developing\n\nTo run tests, you can use the docker [Plugin Tester](https://github.com/buildkite-plugins/buildkite-plugin-tester):\n\n```bash\ndocker run --rm -ti -v \"${PWD}\":/plugin buildkite/plugin-tester:latest\n```\n\n## License\n\nMIT (see [LICENSE](LICENSE))\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbuildkite-plugins%2Fdocker-cache-buildkite-plugin","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbuildkite-plugins%2Fdocker-cache-buildkite-plugin","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbuildkite-plugins%2Fdocker-cache-buildkite-plugin/lists"}