Oci

Developer reference: this page includes exported implementation details. BUILD authors should prefer the User API reference.

ociPull

const ociPull

Declare an OCI image pull label: fetches repo:tag (or repo@digest) into the shared oci-storage named cache as an OCI-layout directory, for use as an ociBuild() base or an ociPush() source.

Parameter	Type	Description
opts	object
opts.repo	string	Image repository, e.g. "docker.io/library/alpine" or "ghcr.io/org/image".
[opts.tag]	string	Mutable tag — resolved to a digest at build time via `crane digest`.
[opts.digest]	string	Immutable `sha256:...` digest — skips the resolve step entirely.

Returns: object Exported label handle.

ociPullBuild

const ociPullBuild

Resolve/pull an ociPull() label: an immutable digest, resolved once (impurely — a tag can move) if only a tag was given, then a cached fetch of that digest's OCI-layout directory into oci-storage.

Parameter	Type	Description
handle	object	Label handle returned by ociPull().

Returns: Promise<{ ociLayoutPath: string, digest: string }>

ociPullPackage

const ociPullPackage

Package an ociPull() label: writes the pulled image's OCI-layout directory out as a dist/.../image.tar oci-archive tarball, loadable via podman load / docker load. will contain an image.tar.

Parameter	Type	Description
handle	object	Label handle returned by ociPull().

Returns: Promise<object> An artifact(...) whose published dist/ path

ociBuild

const ociBuild

Declare an OCI image build label: composes base plus layers into a new image by hand-assembling its OCI layout (layer blobs, config blob, manifest blob, index.json) — no Dockerfile, no commands executed inside a container. One or more file-staging specs; each becomes one deterministic layer tarball. Deliberately no platforms/multi-arch surface yet — single-manifest only for this pass. When multi-arch support is added, it attaches here (an OCI index assembled via crane index append over one build per platform) without needing to change layers'/base's shape.

Parameter	Type	Description
opts	object
[opts.path="."]	string	Directory (relative to the declaring BUILD.js) `layers[].srcs` glob against.
opts.base	object	"scratch"
opts.layers	Array<{srcs: string[], path: string, exclude?: string[], uid?: number, gid?: number, mode?: string}>
[opts.entrypoint]	string[]	Image ENTRYPOINT.
[opts.cmd]	string[]	Image CMD.
[opts.env]	Record<string,string>	Image environment variables.
[opts.labels]	Record<string,string>	Image labels.
[opts.user]	string	Image USER.
[opts.workdir]	string	Image WORKDIR.

Returns: object Exported label handle.

ociBuildBuild

const ociBuildBuild

Undocumented.

ociBuildPackage

const ociBuildPackage

Package an ociBuild() label: writes the composed image's OCI-layout directory out as a dist/.../image.tar oci-archive tarball, loadable via podman load / docker load. will contain an image.tar.

Parameter	Type	Description
handle	object	Label handle returned by ociBuild().

Returns: Promise<object> An artifact(...) whose published dist/ path

ociPush

const ociPush

Declare an OCI image push label: publishes an ociPull()/ociBuild() image to repo:tag.

Parameter	Type	Description
opts	object
opts.image	object	An ociPull()/ociBuild() label handle.
opts.repo	string	Destination repository.
opts.tag	string	Destination tag.

Returns: object Exported label handle.

ociPushBuild

const ociPushBuild

Undocumented.

ociMirror

const ociMirror

Declare an OCI mirror label: re-hosts an image from one registry ref to another via crane copy (registry-to-registry, no local disk materialization) — e.g. mirroring a public upstream image into an internal registry without a Dockerfile.

Parameter	Type	Description
opts	object
opts.from	object	Source ref: `{ repo, tag }` or `{ repo, digest }`.
opts.to	object	Destination ref: `{ repo, tag }`.

Returns: object Exported label handle.

ociMirrorBuild

const ociMirrorBuild

Undocumented.