boringcache/buildkit-action

Cache once. Reuse everywhere.

BoringCache is a universal build artifact cache for CI, Docker, and local development. It stores and restores directories you choose so build outputs, dependencies, and tool caches can be reused across environments.

BoringCache does not run builds and is not tied to any build tool. It works with any language, framework, or workflow by caching directories explicitly selected by the user.

Caches are content-addressed and verified before restore. If identical content already exists, uploads are skipped. The same cache can be reused in GitHub Actions, Docker/BuildKit, and on developer machines using the same CLI.

This action caches BuildKit layer caches (the directories used by BuildKit). It does not cache Docker images unless you push them. Caches can be reused outside Docker builds.

Quick start

- uses: boringcache/buildkit-action@v1
  with:
    buildkit-host: tcp://127.0.0.1:1234
    workspace: my-org/my-project
    image: ghcr.io/${{ github.repository }}
    tags: latest,${{ github.sha }}
  env:
    BORINGCACHE_API_TOKEN: ${{ secrets.BORINGCACHE_API_TOKEN }}

Cache is automatically restored before build and saved after.

Mental model

This action manages a local BuildKit cache directory and a BoringCache tag.

• It restores the cache into a local directory before the build.
• It runs buildctl with cache import/export.
• It saves the updated cache back to BoringCache in a post step.

You still control your Dockerfile, build args, and output settings.

Notes:

• TLS inputs accept either file paths or raw PEM strings.
• Set output for custom buildctl outputs (for example, type=local,dest=./out).
• For Docker buildx builds, use boringcache/docker-action instead.

Common patterns

Simple buildctl build

- uses: boringcache/buildkit-action@v1
  with:
    buildkit-host: tcp://127.0.0.1:1234
    workspace: my-org/my-project
    image: ghcr.io/${{ github.repository }}
    tags: latest,${{ github.sha }}
  env:
    BORINGCACHE_API_TOKEN: ${{ secrets.BORINGCACHE_API_TOKEN }}

Separate restore/save actions (advanced)

- uses: boringcache/buildkit-action/restore@v1
  id: cache
  with:
    workspace: my-org/my-project

- name: Build with buildctl
  run: |
    buildctl --addr $BUILDKIT_HOST build \
      --frontend dockerfile.v0 \
      --local context=. \
      --local dockerfile=. \
      --import-cache type=local,src=${{ steps.cache.outputs.cache-dir }} \
      --export-cache type=local,dest=${{ steps.cache.outputs.cache-dir }},mode=max \
      --output type=image,name=my-app:latest,push=false

- uses: boringcache/buildkit-action/save@v1
  with:
    workspace: my-org/my-project
    cache-tag: ${{ steps.cache.outputs.cache-tag }}
    cache-dir: ${{ steps.cache.outputs.cache-dir }}

Inputs

Input	Required	Default	Description
buildkit-host	Yes	-	BuildKit address (e.g., tcp://buildkit:1234).
image	Yes	-	Base image name (e.g., ghcr.io/org/app).
workspace	No	repo name	Workspace in org/repo form. Defaults to BORINGCACHE_DEFAULT_WORKSPACE or repo name.
context	No	.	Build context path.
dockerfile	No	Dockerfile	Dockerfile path.
tags	No	latest	Image tags (comma or newline separated).
push	No	false	Push image to registry.
output	No	-	Custom buildctl --output string. When set, image, tags, and push are ignored.
build-args	No	-	Build arguments (newline-separated KEY=VALUE).
secrets	No	-	BuildKit secrets (newline separated).
ssh	No	-	SSH specs for BuildKit (newline separated).
target	No	-	Target build stage.
platforms	No	-	Target platforms (e.g., linux/amd64,linux/arm64).
no-cache	No	false	Build without cache.
cache-mode	No	max	BuildKit cache mode (min or max).
cache-tag	No	slugified image name	Cache tag for BoringCache.
cli-version	No	v1.0.0	BoringCache CLI version. Set to skip to disable installation.
buildkit-tls-ca	No	-	TLS CA certificate (path or PEM).
buildkit-tls-cert	No	-	TLS client certificate (path or PEM).
buildkit-tls-key	No	-	TLS client key (path or PEM).
buildkit-tls-skip-verify	No	false	Skip TLS verification.

Outputs

Output	Description
digest	Image digest from buildctl metadata
cache-hit	Whether cache was restored from BoringCache

Platform behavior

Platform scoping is what makes it safe to reuse caches across machines.

By default, caches are isolated by OS and architecture. This action uses your existing BuildKit daemon, so ensure it supports the target platforms you specify.

Environment variables

Variable	Description
BORINGCACHE_API_TOKEN	API token for BoringCache authentication
BORINGCACHE_DEFAULT_WORKSPACE	Default workspace if not specified in inputs

Troubleshooting

• Cache not restored: ensure BORINGCACHE_API_TOKEN is set and the workspace exists.
• TLS connection failures: verify buildkit-tls-* values and buildkit-tls-skip-verify.
• buildctl output missing: check output and push settings.

Release notes

See https://github.com/boringcache/buildkit-action/releases.

License

MIT