Docker Syntax Buildkit

docker-syntax-buildkit

Quick Reference

Syntax Directive

ALWAYS include at the very top of every Dockerfile, before any other instruction:

# syntax=docker/dockerfile:1

This enables heredoc syntax, --mount flags, --chmod/--link/--parents/--exclude on COPY/ADD, the # check directive, and all other BuildKit extensions. ALWAYS use docker/dockerfile:1 (not 1.0 or a fixed minor version) to get the latest stable features.

Mount Types Overview

| Mount Type | Purpose | Key Use Case | |------------|---------|-------------| | cache | Persistent cache directories across builds | Package manager caches (apt, npm, pip, go) | | secret | Access credentials without baking into layers | API keys, tokens, registry auth | | ssh | Forward host SSH agent during build | Cloning private Git repositories | | bind | Mount context or stage files (read-only default) | Large source trees, cross-stage file access | | tmpfs | Temporary in-memory filesystem | Scratch space for compilation, tests |

Platform ARGs (Automatic in BuildKit)

| ARG | Example Value | Purpose | |-----|---------------|---------| | TARGETPLATFORM | linux/amd64 | Full target platform string | | TARGETOS | linux | Target operating system | | TARGETARCH | amd64 | Target architecture | | TARGETVARIANT | v7 | Target variant (e.g., ARM version) | | BUILDPLATFORM | linux/amd64 | Host platform running the build | | BUILDOS | linux | Host operating system | | BUILDARCH | amd64 | Host architecture |

These ARGs are available automatically without explicit ARG declaration. ALWAYS declare them with ARG TARGETOS TARGETARCH inside a stage to use them in RUN instructions.

Critical Warnings

NEVER put secrets in ENV or ARG instructions -- they are visible in docker history and image layers. ALWAYS use --mount=type=secret instead.

NEVER omit the syntax directive when using BuildKit features -- without # syntax=docker/dockerfile:1, mount flags and heredoc syntax cause parse errors.

NEVER use sharing=shared (the default) for apt cache mounts -- apt requires exclusive access. ALWAYS use sharing=locked for apt caches.

NEVER assume secret mount contents trigger cache invalidation -- they do NOT. If a secret changes and the build must reflect that change, pass a CACHEBUST build arg.

ALWAYS use set -e in heredoc RUN blocks -- without it, individual command failures are silently ignored and the build continues.

---

Mount Type Decision Tree

Need to mount something during RUN?
|
+-- Persisting package downloads between builds?
|   --> type=cache (see Cache Mount Patterns below)
|
+-- Accessing credentials/tokens during build?
|   --> type=secret (file or env mode)
|
+-- Cloning private Git repos via SSH?
|   --> type=ssh
|
+-- Reading source files without creating a COPY layer?
|   +-- From build context? --> type=bind,target=.
|   +-- From another stage? --> type=bind,from=,target=
|
+-- Need temporary scratch space (not persisted)?
    --> type=tmpfs

---

Heredoc Syntax

Multi-Line RUN

Run multi-line scripts without && chaining:

# syntax=docker/dockerfile:1

RUN > /etc/nginx/nginx.conf
CONFIGURE

---

Cache Mount Patterns

ALWAYS use cache mounts for package managers. The cache is cumulative -- even when a layer rebuilds, only new/changed packages are downloaded.

| Package Manager | Cache Target(s) | Sharing Mode | |----------------|-----------------|--------------| | apt | /var/cache/apt + /var/lib/apt | locked (required) | | npm | /root/.npm | shared (default) | | yarn | /usr/local/share/.cache/yarn | shared | | pnpm | /root/.local/share/pnpm/store | shared | | pip | /root/.cache/pip | shared | | Go | /go/pkg/mod + /root/.cache/go-build | shared | | Cargo (Rust) | /app/target/ + /usr/local/cargo/git/db + /usr/local/cargo/registry/ | shared | | Maven | /root/.m2/repository | shared | | Bundler (Ruby) | /root/.gem | shared | | NuGet (.NET) | /root/.nuget/packages | shared | | Composer (PHP) | /tmp/cache | shared |

See [references/examples.md](references/examples.md) for complete patterns per package manager.

Cache Mount Full Syntax

--mount=type=cache,target=[,id=][,sharing=][,from=][,source=][,mode=][,uid=][,gid=]

| Option | Default | Purpose | |--------|---------|---------| | target | (required) | Directory to cache | | id | value of target | Cache identity (share across stages with same id) | | sharing | shared | shared: concurrent access; locked: exclusive; private: per-build copy | | from | (none) | Initialize cache from a build stage | | source | (none) | Path within from to seed cache | | mode | 0755 | Directory permissions | | uid | 0 | Owner user ID | | gid | 0 | Owner group ID |

---

Secret Mounts

As File (default)

RUN --mount=type=secret,id=aws,target=/root/.aws/credentials \
    aws s3 cp s3://bucket/file /dest

Build: docker build --secret id=aws,src=$HOME/.aws/credentials .

As Environment Variable

RUN --mount=type=secret,id=TOKEN,env=TOKEN \
    some-command  # $TOKEN is available

Build: docker build --secret id=TOKEN,src=./token.txt .

Secret Mount Options

| Option | Default | Purpose | |--------|---------|---------| | id | (required) | Secret identifier matching --secret id= | | target | /run/secrets/ | Mount path inside the container | | required | false | Fail build if secret is not provided | | env | (none) | Expose as environment variable instead of file | | mode | 0400 | File permissions | | uid | 0 | Owner user ID | | gid | 0 | Owner group ID |

---

SSH Mounts

RUN --mount=type=ssh \
    git clone git@github.com:org/private-repo.git /app

Build: docker build --ssh default .

| Option | Default | Purpose | |--------|---------|---------| | id | default | SSH agent socket identifier | | target | /run/buildkit/ssh_agent.${N} | Mount path for socket | | required | false | Fail build if SSH agent is not available |

ALWAYS add GitHub/GitLab host keys before cloning:

RUN --mount=type=ssh \
    mkdir -p ~/.ssh && ssh-keyscan github.com >> ~/.ssh/known_hosts \
    && git clone git@github.com:org/repo.git /app

---

Bind Mounts

# Mount entire build context (avoids COPY layer)
RUN --mount=type=bind,target=. go build -o /app/hello

# Mount from another stage
RUN --mount=type=bind,from=build,source=/src,target=/source ls /source

# Mount single file
RUN --mount=type=bind,source=requirements.txt,target=/tmp/requirements.txt \
    pip install -r /tmp/requirements.txt

| Option | Default | Purpose | |--------|---------|---------| | target | (required) | Mount destination in container | | source | . (root of context/stage) | Source path | | from | build context | Named stage or image to mount from | | rw | false | Set true for read-write (changes NOT persisted) |

---

Tmpfs Mounts

RUN --mount=type=tmpfs,target=/tmp gcc -o /app/binary source.c

| Option | Default | Purpose | |--------|---------|---------| | target | (required) | Mount path | | size | unlimited | Size limit in bytes |

---

Cross-Compilation Pattern

# syntax=docker/dockerfile:1

FROM --platform=$BUILDPLATFORM golang:1.22-alpine AS build
ARG TARGETOS TARGETARCH

WORKDIR /src
COPY go.mod go.sum ./
RUN --mount=type=cache,target=/go/pkg/mod go mod download

COPY . .
RUN --mount=type=cache,target=/go/pkg/mod \
    --mount=type=cache,target=/root/.cache/go-build \
    GOOS=$TARGETOS GOARCH=$TARGETARCH go build -o /bin/app ./cmd

FROM alpine:3.19
COPY --from=build /bin/app /usr/bin/app
ENTRYPOINT ["/usr/bin/app"]

Build multi-platform: docker buildx build --platform linux/amd64,linux/arm64 -t myapp:latest .

---

Cache Backends

| Backend | Flag | Use Case | |---------|------|----------| | Inline | type=inline | Embed cache metadata in output image | | Registry | type=registry,ref= | Store cache as separate registry image | | Local | type=local,dest= | Local filesystem directory | | GitHub Actions | type=gha | GitHub Actions cache service | | S3 | type=s3,bucket=,region= | AWS S3 storage | | Azure Blob | type=azblob,account_url= | Azure Blob storage |

Cache Modes

• min (default) -- Only caches exported layers. Smaller cache, fewer hits.
• max -- Caches ALL intermediate layers. Larger cache, more hits. ALWAYS use mode=max in CI/CD.

Registry Cache (CI/CD)

docker buildx build --push -t registry/app:latest \
  --cache-to type=registry,ref=registry/app:buildcache,mode=max \
  --cache-from type=registry,ref=registry/app:buildcache .

GitHub Actions Cache

docker buildx build \
  --cache-to type=gha,mode=max \
  --cache-from type=gha .

---

Reference Links

• [references/mounts.md](references/mounts.md) -- Complete reference for all 5 mount types with every option
• [references/examples.md](references/examples.md) -- Cache mount patterns per package manager, secret patterns, SSH patterns
• [references/anti-patterns.md](references/anti-patterns.md) -- BuildKit feature misuse and corrections

Official Sources

• https://docs.docker.com/reference/dockerfile/
• https://docs.docker.com/build/buildkit/
• https://docs.docker.com/build/cache/
• https://docs.docker.com/build/cache/backends/
• https://docs.docker.com/build/building/multi-stage/

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: Impertio-Studio
• Source: Impertio-Studio/Docker-Claude-Skill-Package
• License: MIT

Install and usage instructions live in the source repository linked above.