Features on Yamlfile

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).

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.