Skip to content
Documentation

Docs / Adapter commands / BuildKit

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 BuildKit without Docker on Linux

Add runtime = "native" under [adapters.buildkit], or run boringcache buildkit --runtime native. BoringCache downloads the compatible binaries, starts a daemon for the command, and stops it afterward. Linux amd64 and arm64 are supported with root privileges, util-linux unshare and mount utilities. No sudo command runs automatically. The native worker uses host networking. Rootless operation and remote daemons are not supported.

Connect to your own local daemon

Use buildctl --addr or BUILDKIT_HOST to select a compatible patched BoringCache BuildKit daemon on the same Linux host. The address flag takes precedence over the environment. Unix sockets and loopback TCP with mutual TLS are supported; pass --tlsdir or the CA, client certificate and key through buildctl. BoringCache verifies compatibility before the build and leaves your daemon running. This path supports layer caching and image publication; mount-cache, tool-cache and daemon configuration require a daemon started by BoringCache.

Run the same solve

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

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

  • The default runtime uses Docker. On Linux amd64 or arm64, --runtime native runs BuildKit directly and downloads its compatible client and daemon.
  • Native operation requires root privileges, util-linux unshare, mount utilities and a writable filesystem for BuildKit state. Rootless operation is not supported.
  • An external local daemon must be a compatible patched BoringCache BuildKit release. Stock upstream BuildKit does not include the BoringCache cache backend. Make buildctl available when using an external daemon.
  • Do not pass separate import-cache or export-cache flags; the adapter injects the planned cache refs.

Configuration and cache behavior

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. BoringCache reads this configuration when it starts the daemon. When connecting to an existing daemon, configure that daemon separately.

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 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. max-parallelism limits concurrent build steps. For Docker-managed workers, BORINGCACHE_MANAGED_BUILDKIT_CPUS limits the container CPU quota and BORINGCACHE_MANAGED_BUILDKIT_CPUSET_CPUS selects host CPU IDs. For native workers, set resource limits on the service that invokes BoringCache; Docker CPU and image overrides are rejected.

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. Other paths refer to the daemon host in native mode and the worker container in Docker mode. BoringCache manages the state directory, OCI worker and client connection; incompatible root, grpc.address, grpc.tls, or worker-enable settings fail before startup.

Use mount and tool caches with native builds

The native runtime supports --mount-cache and --tool-cache with the same tags and read-only controls as Docker-managed builds. BoringCache isolates helper credentials for each daemon and passes tool configuration through buildctl secrets. Use separate changed-layer runs to verify mount or tool reuse; a layer-cache hit does not prove that either cache was used.

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@1781572d7b3ec5aef652f8ba479b981439b2776b # v1.48.2
  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. Run reports rank observed vertex durations, including separately measured cached-layer loading. These observations do not establish a critical path or saved execution time. Compare benchmark runs by build family and workload to find the closest match for your project.

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.