Documentation

BuildKit adapter

Use buildctl directly while BoringCache supplies the managed cache import and export. BuildKit keeps control of the solve graph, frontend, local inputs, and output.

Command: boringcache buildkit
Protocol: BuildKit cache import and export through the managed type=boringcache backend
Action: mode: buildkit

How the adapter works

Run the same solve

Keep the frontend, build graph, local inputs, secrets, and output in the buildctl command you already use.

Add shared cache

BoringCache adds the import and export refs from `.boringcache.toml` and the current trust policy.

Publish from trusted jobs

Restore-only jobs import cache. Save-capable trusted jobs publish the new cache state.

Share mounts across separate image graphs

One tag addresses the layer cache. Add --mount-namespace so two jobs that need their own image graphs can still share cache mounts: give each job its own tag and both the same namespace. A bare value covers every mount; MOUNT_ID=NAMESPACE addresses one --mount=type=cache id, so a shared registry can sit beside separate target directories. Mounts you do not name keep the tag's identity. Requires --mount-cache. Set it in .boringcache.toml as adapters.buildkit.mount-namespace.

Two jobs can publish one namespace

A namespaced mount is shared on purpose, so publication combines rather than replaces. Before publishing, the job checks whether another job has published since its own restore; if so it merges the published files it does not already have, keeping its own copy of every shared path, and commits against the snapshot it merged. A job that loses that race merges again and retries instead of dropping its work. Deleted files are not propagated between jobs, so a namespace grows until its entry expires.

Configure BuildKit with TOML

Place buildkitd.toml in the directory where you run the command or an ancestor within the repository. BoringCache uses the nearest file, stopping at the Git root. Outside Git it stops at the .boringcache.toml directory, or the invocation directory when no repo config exists. Without a file, the worker uses its defaults.

Select another config file

Use --buildkitd-config path/to/buildkitd.toml before --, or set buildkitd-config under [adapters.buildkit] in .boringcache.toml. The CLI flag wins over the repo setting and discovery. CLI paths are relative to the invocation directory; repo paths are relative to .boringcache.toml. A selected missing, unreadable, or invalid file fails the build. Config files must be regular files no larger than 1 MiB.

Apply native worker settings

Use native BuildKit settings such as [worker.oci] max-parallelism = 1, registry mirrors, DNS, worker labels, and garbage-collection policies. Explicit TOML snapshotter and gc values take precedence over BoringCache defaults, including the snapshotter environment setting. Changed settings recreate the worker before the next build. max-parallelism limits concurrent build steps; BORINGCACHE_MANAGED_BUILDKIT_CPUS limits the worker container CPU quota and BORINGCACHE_MANAGED_BUILDKIT_CPUSET_CPUS selects host CPU IDs.

Keep file paths and connections explicit

Registry CA and client keypair files are read relative to the selected TOML file and copied privately into the worker. Certificate changes also recreate it. Other paths refer to files inside the worker container. BoringCache manages /var/lib/buildkit, the OCI worker, and the local Docker connection; incompatible root, grpc.address, grpc.tls, or worker-enable settings fail clearly. Use the native TOML format without changing these managed settings.

Set up BuildKit

Keep the cache tag and the buildctl build command in .boringcache.toml, then run boringcache buildkit. BoringCache adds the configured cache import and export while keeping your frontend, local inputs, and output unchanged.

[adapters.buildkit]
tag = "buildkit-cache"
command = ["buildctl", "build", "--frontend", "dockerfile.v0", "--local", "context=.", "--local", "dockerfile=."]

# Run: boringcache buildkit

Before the first run

Make buildctl available before invoking BoringCache.
Provide a reachable BuildKit daemon when the workflow starts its own buildkitd.
Do not pass separate import-cache or export-cache flags; the adapter injects the planned cache refs.

Use the same adapter in GitHub Actions

BuildKit mode runs the command committed under [adapters.buildkit], adds the shared cache refs, and completes the solve in the Action step.

.github/workflows/ci.yml

- uses: boringcache/one@f0fb9b2d926a32b10c543e92093ba00c5a291b79 # v1.33.0
  with:
    trust-policy: auto
    mode: buildkit

Approve the repository through Connect CI and grant the job contents: read and id-token: write. The Action uses that Machine connection. Pull requests restore by default; trusted jobs may publish. See the authentication example in the GitHub Actions reference for scoped credentials when OIDC is unavailable.

GitHub Actions reference

Benchmarks

The Docker and BuildKit adapters use the same managed BoringCache backend. Compare benchmark runs by build family and workload to find the closest match for your project.

2.9×

Faster Docker builds without layer hits

Across three Mastodon source changes on AMD64 and ARM64, ccache and persistent mounts averaged 2m 39s, compared with 7m 34s for cache:false.

Open run →

11–60%

Faster Docker builds

BoringCache cut measured build time by 11–60% across 6 public Docker comparisons with actions/cache.

Open run →

36%

Faster across every rebuild

Across three independently seeded trials, BoringCache + ccache + mount cache rebuilt Immich base images in 74m 23s, compared with 115m 47s for its GHCR registry cache.

Open run →

14%

Faster before warm reuse

BoringCache + ccache + mount cache built the Discourse ARM64 image graph in 20m 06s, compared with 21m 56s for BoringCache layers and 23m 26s for actions/cache.

Open run →

Pinned Docker workloads

The public catalog includes Go build cache, sccache, and Rust target cache mounts inside Docker builds.

Open run →

Stirling-PDF CI · 25% faster median
Open run →
Immich base images · 36% faster
Open run →
Discourse ARM64 cold seed · 14% faster
Open run →
Proteus Rust Docker run
Open run →

BuildKit cache page All benchmarks

Tool reference

Check the tool's own reference when you need cache-key rules, build settings, or version-specific behavior.

All adapter commands

Compare every supported command, protocol, and Action mode in one place.

Adapter command index →

Need help or found something unclear? Open an issue or browse the CLI repo.