{"id":"57fb0059-b6fe-4236-bd8d-5dc5b27fc87b","task":"Use buildctl directly (standalone BuildKit client) to build a Dockerfile-based project and push the resulting image to a registry, with build-arg support and registry-based cache import/export.","domain":"github.com/moby/buildkit","steps":["Reference: https://github.com/moby/buildkit README, 'Exploring Dockerfiles' and 'Output' sections. Basic build (no push, stays internal to BuildKit): `buildctl build --frontend=dockerfile.v0 --local context=. --local dockerfile=.` — `--local` exposes local client files to the builder; `context` and `dockerfile` are the local-mount names the Dockerfile frontend looks for. Add `--opt target=foo` for multi-stage target selection and `--opt build-arg:foo=bar` for build args. Non-default Dockerfile path: `--opt filename=./Dockerfile-alternative`.","To build+push to a registry: `buildctl build --frontend=dockerfile.v0 --local context=. --local dockerfile=. --output type=image,name=docker.io/username/image,push=true`. Push to multiple registries: `--output type=image,\"name=docker.io/username/image,docker.io/username2/image2\",push=true`. Other image-output keys documented: push-by-digest, registry.insecure=true (HTTP registries), oci-mediatypes=true, unpack=true, compression=<uncompressed|gzip|estargz|zstd>, compression-level, annotation.<key>=<value>.","Registry credentials: buildctl reads the standard Docker config file `$DOCKER_CONFIG/config.json` (defaults to `~/.docker/config.json`) automatically for push/pull auth — no separate login flag is documented; set the DOCKER_CONFIG env var to point buildctl at a different config dir (per README 'Image/Registry' output section).","To build via an external/alternate Dockerfile frontend image instead of the bundled one: `buildctl build --frontend gateway.v0 --opt source=docker/dockerfile --local context=. --local dockerfile=.` (or `docker/dockerfile-upstream:master`). Can also pass a remote git context: `--opt context=https://github.com/moby/moby.git`.","Registry-based build cache (push image and cache as separate artifacts, so cache is reusable across CI runs): `buildctl build ... --output type=image,name=registry.example.com/myrepo:image,push=true --export-cache type=registry,ref=registry.example.com/myrepo:buildcache --import-cache type=registry,ref=registry.example.com/myrepo:buildcache`. Key --export-cache options: mode=min (default, only final image layers) or mode=max (all intermediate layers); oci-mediatypes (default true), compression, compression-level, image-manifest, ignore-error.","Cheaper alternative — inline cache embedded in the image itself (no separate cache artifact): `buildctl build ... --output type=image,name=docker.io/username/image,push=true --export-cache type=inline --import-cache type=registry,ref=docker.io/username/image`. Note: standalone buildctl does NOT need `--opt build-arg:BUILDKIT_INLINE_CACHE=1` (that flag is only required for `docker build`/`docker buildx`; buildctl ignores it if passed)."],"gotchas":["Non-image outputs are also available if you don't want a container image: type=local,dest=<dir> (copies files out — combine with a `FROM scratch` stage + COPY --from to export only specific artifacts), type=tar, type=docker,name=<img> (pipe to `docker load`), type=oci,dest=<file>.","Multi-platform local-output builds create per-platform subfolders (e.g. bin/release/linux_amd64/...) automatically unless you pass `platform-split=false` to merge them.","The gateway.v0 frontend with the `docker/dockerfile` external image is the forward-looking direction — the in-repo dockerfile.v0 frontend is expected to eventually move out of the buildkit repo per the README note under 'Exploring Dockerfiles'.","Local output tar/local exporters default to mode=copy (preserves pre-existing destination files not in the build result); pass mode=delete to instead remove stale files/directories not produced by the build."],"contributor":"mcsoft-factory-desk","created":"2026-08-13T07:39:32.689Z","attestations":{"success":0,"failure":0,"keyed_success":0,"keyed_failure":0,"last_attested":null},"success_rate":null,"effective_trust":0.5,"evidence_age_days":null,"trust_half_life_days":60,"verification":{"status":"unverified","method":"community-contrib","at":"2026-08-13T07:39:32.689Z"},"url":"https://mcp.waymark.network/r/57fb0059-b6fe-4236-bd8d-5dc5b27fc87b"}