# Use Docker Buildx For Building

> Use when building or validating Docker images for repository components with Docker Buildx, especially when the Dockerfile, build context, target platforms, image namespace, component name, or runtime smoke check must be determined from the current repository.

- Skill: `moeru-ai/use-docker-buildx-for-building` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add moeru-ai/use-docker-buildx-for-building`
- Raw SKILL.md: https://api.skillmd.com/api/skills/moeru-ai/use-docker-buildx-for-building/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Web & Frontend
- Author: moeru-ai (https://skillmd.com/u/moeru-ai)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/moeru-ai/use-docker-buildx-for-building

---


# Use Docker Buildx for Building

## Core Principle

Derive every build command from repository inspection. Inspect the current user, Git remote and organization or namespace, repository name, component name, Dockerfile, build context, target platform, and runtime contract yourself. Do not provide or rely on a naming helper or build helper script.

## Workflow

1. Read every applicable `AGENTS.md` and the repository's build documentation before forming a command.
2. Inspect `id -un`, the Git root, configured Git remotes, the current branch's tracking remote, and all relevant Dockerfiles.
3. Read the selected Dockerfile and related manifests. Derive the positional build context only from local `COPY` and `ADD` sources in the default local context, and ensure those sources resolve inside it. Classify `COPY --from` sources as stages, images, or named contexts; identify named contexts and remote `ADD` sources without treating them as default-local sources. Determine any required `--build-context` inputs and authentication separately.
4. Determine the component name and target platform from repository evidence, deployment manifests, CI configuration, and the intended runtime. Ask the user when the component or platform remains ambiguous.
5. Select the current branch's tracking remote first, then a remote designated by repository build documentation. Ask the user when neither source identifies one remote or when candidates remain. Form the image name literally as `test.<current-username>.local/<org-or-namespace>/<repo-name>/<component-name>:<tag>`. Substitute every segment with an observed value, derive the organization or namespace from the selected remote, and use `latest` only when no tag was requested or established by repository convention. Validate the namespace, repository, component, tag, and complete name as a legal image reference. If normalization would change identity and no repository convention resolves it, ask instead of guessing.
6. Make each local smoke build, loaded tag, and verification correspond to exactly one explicit platform. Build, load, tag, and verify multiple target platforms separately. Construct every build command with an explicit `--platform <platform>`, `-f <dockerfile>`, the inspected build context, `--tag <image-name>`, and `--load`. Repeat the explicit `--platform` option in every build command; never rely on an ambient platform default. Before running a non-host platform, confirm support in the builder, local image store, emulation layer, and container runtime.
7. Always retain `--load`; the subsequent local `docker run` verification depends on the image being loaded into the local Docker image store.
8. Inspect the built image, then actually run and verify the same target platform according to its `ENTRYPOINT`, `CMD`, exposed ports, required arguments, and documented runtime contract. Pass `--platform <platform>` explicitly to `docker run` when the target is not the host platform or platform selection could be ambiguous; omit it only for a host-platform image loaded under a single-platform tag. For a one-shot command, use `docker run --rm`. For a long-running service, assign a unique container name or capture its container ID, start it in the background, bind published ports only to loopback, and prefer a dynamic host port when possible. Perform a bounded readiness, health, or protocol check, and use a trap or `finally` cleanup to stop and `rm -f` that exact container even when startup or verification fails.
9. Keep secrets out of `--build-arg`, Dockerfile `ARG` and `ENV`, command-line literals, `COPY`, and the build context. Inspect `.dockerignore` to ensure credentials are excluded. For private dependencies, use BuildKit `--secret` or `--ssh` with matching `RUN --mount=type=secret` or `RUN --mount=type=ssh` consumption so secrets do not enter image layers.

## Quick Reference

| Decision | Evidence to inspect |
| --- | --- |
| Current username | `id -un` |
| Repository root and name | Git root and its basename |
| Selected remote and namespace | Current branch tracking remote, then repository build documentation |
| Component name | Dockerfile purpose and path, manifests, build docs, CI configuration |
| Dockerfile | Repository Dockerfile inventory and component documentation |
| Build context | Default-local `COPY` and `ADD` sources, source classification, repository layout |
| Target platform | Deployment manifests, CI configuration, base-image support, runtime target |
| Runtime smoke check | Dockerfile `ENTRYPOINT`, `CMD`, `EXPOSE`, health checks, and runtime docs |
| Image reference validity | Docker image-reference grammar and repository naming conventions |
| Secret handling | `.dockerignore`, private-dependency requirements, BuildKit secret or SSH mounts |

## Fictional Example

Treat the following values as fictional, not defaults. Reinspect them on every use: user `mia`, remote `acme/widgets`, component `api`, Dockerfile `services/api/Dockerfile`, repository-root context, and platform `linux/arm64`.

```sh
docker buildx build --platform linux/arm64 -f services/api/Dockerfile . --tag test.mia.local/acme/widgets/api:latest --load
docker run --rm test.mia.local/acme/widgets/api:latest --version
```

## Common Mistakes

- Do not guess the build context or mistake `COPY --from`, named contexts, or remote `ADD` sources for default-local sources.
- Do not hardcode usernames, namespaces, repository names, components, tags, Dockerfiles, contexts, or platforms.
- Do not omit `--load` from a build intended for local verification.
- Do not stop after a successful build; inspect and actually run the loaded image.
- Do not leave a service running, use an unbounded readiness check, expose smoke-test ports beyond loopback, or clean up a container other than the exact one started.
- Do not pass secrets through build arguments, Dockerfile variables, literals, copied files, or the build context; use BuildKit secret or SSH mounts and exclude credentials with `.dockerignore`.