Yamlfile

Getting Started

Mon, 01 Jan 0001 00:00:00 +0000

Prerequisites#

Docker with BuildKit enabled (Docker 23+ or DOCKER_BUILDKIT=1).

Using a Released Image#

The official images are published to ghcr.io/builderhub/yamlfile.

In your Yamlfile (or any file you pass with -f):

# syntax=ghcr.io/builderhub/yamlfile:latest
apiVersion: v1alpha1

targets:
 myapp:
 from: golang:1.25
 steps:
 - run:
 command: go build -o /out/myapp .

Then build with:

docker buildx build -f MyYamlfile \
 --output type=image,name=myapp,push=false \
 .

If your Yamlfile defines multiple top-level targets and you don’t want the default (first reachable), pass --target:

run.script — Baked-in Script Execution

Mon, 01 Jan 0001 00:00:00 +0000

One of Yamlfile’s most useful “baked-in” features is run.script.

steps:
 - run:
 script: ./scripts/install-deps.sh
 env:
 DEBIAN_FRONTEND: noninteractive

How it works (without you writing a COPY)#

You list the script path in your Yamlfile.
Yamlfile reads the file content from your build context (only the script you declared).
A temporary scratch layer is created with the script content and executable permissions.
The script is mounted read-only into the RUN filesystem at a generated path (e.g. /.yamlfile-script-...).
The script is executed directly (or via /bin/sh).

Result: the script runs exactly as if it had been copied in, but it never appears in any layer of the final image unless you later explicitly copy it from the build stage.

Secrets (file and env forms)

Mon, 01 Jan 0001 00:00:00 +0000

Yamlfile supports BuildKit’s native secret mounts in a declarative way.

- run:
 script: ./scripts/push-to-registry.sh
 secrets:
 - id: registry_token
 env: REGISTRY_TOKEN  # injected only for this run

 - id: netrc
 target: /root/.netrc  # file form
 mode: 0600
 optional: true

File form vs. Env form#

target: (or omitting it) → secret appears as a file (default location /run/secrets/<id>).
env: → secret is exported as an environment variable inside the RUN (the value is masked in logs by BuildKit).

Both map directly to BuildKit’s --mount=type=secret mechanism (file mount or env= form).

Syntax Reference

Mon, 01 Jan 0001 00:00:00 +0000

This page is the authoritative reference for the structure understood by the Yamlfile BuildKit frontend.

Status: The format is designed to be forward-compatible (unknown fields are retained via extensions). Most of the documented features work when you build with Yamlfile:

defaults.platform and per-target platform: are honored (target.platform > defaults.platform > client --platform / dockerui). See the Platform section below.

builds: + component:target cross-file refs — you can write the syntax, and it will give you a clear error if you try to use it. Actually loading and using targets from other Yamlfiles is not yet supported.

Dependency graphs (including cycle detection) are fully supported. Independent targets are not artificially serialized. See Parallelism & Graphs for details.

See Development for scope. Multi-file runtime remains the main pending item.

Multi-file Builds & Cross-Target Copy

Mon, 01 Jan 0001 00:00:00 +0000

Note: You can write builds: sections and use component:target references (e.g. from: "torch:base") in your Yamlfile today. These will be accepted, but cross-file builds are not yet supported at runtime. Only targets defined in the same Yamlfile can be used with from: and copy.from:. The examples below show the intended future behavior.

Multi-file orchestration will let a single top-level Yamlfile coordinate builds defined in other Yamlfiles (often in subdirectories) and then copy artifacts across them.

Parallelism & Dependency Graphs

Mon, 01 Jan 0001 00:00:00 +0000

When you define multiple top-level targets that have no dependency on each other (no from: or copy.from: relationship), Yamlfile prepares them without forcing unnecessary ordering.

What this means for your builds#

Targets that don’t depend on one another won’t block each other.
You don’t have to do anything special. Just write your targets with clear dependencies using from: and copy.from:. Yamlfile figures out what can safely run in parallel.
BuildKit’s execution engine also runs independent operations concurrently and takes advantage of caching.

If you request a specific target (with --target), only the targets it actually needs will be built. Independent “sibling” targets that aren’t required are left alone.

Examples

Mon, 01 Jan 0001 00:00:00 +0000

Minimal#

See examples/minimal.Yamlfile:

apiVersion: v1alpha1

targets:
 hello:
 from: alpine:3.19
 steps:
 - run:
 command: echo "hello from Yamlfile" > /msg.txt
 - run:
 inline: |
 echo "inline shell logic works" >> /msg.txt

Build it:

docker buildx build -f examples/minimal.Yamlfile \
 --build-arg BUILDKIT_SYNTAX=ghcr.io/builderhub/yamlfile:latest \
 --output type=local,dest=/tmp/out \
 .
cat /tmp/out/msg.txt

Multi-target + script + secret (typical pattern)#

A realistic pattern with:

Independent targets (prep, test) that have no dep on each other.
A build target that uses run.script, run.env, and an env: step.
A final target that copies outputs from multiple previous targets.
A secret declared for the build step (supply at docker buildx time with --secret).

See the complete, self-contained file + supporting script:

Why Yamlfile instead of a plain Dockerfile?

Mon, 01 Jan 0001 00:00:00 +0000

Traditional multi-stage Dockerfiles are extremely powerful but become difficult to reason about at scale:

Linear file order + implicit dependencies via FROM foo / COPY --from=foo.
Lots of boilerplate for “download in parallel for cache” patterns (see the giant torch/Dockerfile and torch-extras/Dockerfile in coreweave/ml-containers).
Scripts must be COPYed (or put in heredocs) even when you only want them for the build.
Secret mounts are verbose and easy to get slightly wrong (leaking into layers or logs).
Hard to express “these N independent things can be built in parallel and then combined”.

Yamlfile makes the graph explicit:

Development

Mon, 01 Jan 0001 00:00:00 +0000

Prerequisites#

Docker with BuildKit (23+ recommended).
Nix (for the hermetic dev shell that includes Go, hugo, linters, docker-buildx, etc.).

Setup#

git clone --recurse-submodules https://github.com/BuilderHub/Yamlfile.git
cd Yamlfile
nix develop

If you already cloned without submodules: git submodule update --init --recursive.

Common commands#

make help # list targets
make ci # tests + lint + vet + revive
make test
make generate-schema # (re)generate docs/static/schema/v1alpha1.json from pkg/spec/v1alpha1 (also run by docs)
make docs
make docker-build # current-arch image tagged localhost... or REGISTRY=... TAG=...

See Makefile for the full set (including multi-arch push flows used in release).