OciImage

units.gitops.nyl/v1

Orchestration Resources · Download JSON Schema · Usage guide

Builds and pushes an immutable container image with Docker Buildx.

Consumers read the image ContainerImage artifact by digest. Registry credentials come only from the declared registryAuth keys or env.

Example

apiVersion: units.gitops.nyl/v1
kind: OciImage
metadata:
  name: workloads
spec:
  context:
    path: services/web
  platforms:
    - linux/amd64
  repository: registry.example.com/team/web

Fields

Required means required within the containing object. Optional and nullable are distinct; contextual defaults and requirements are explained with each field.

apiVersion

Required · string

The built-in unit API version, units.gitops.nyl/v1.

const: "units.gitops.nyl/v1"

kind

Required · string

The unit kind, OciImage.

const: "OciImage"

metadata

Required · object

Literal unit name and labels used for environment selection.

Unknown fields are rejected.

metadata.labels

Optional · object

Literal labels used for organization and target selection.

metadata.labels[key]

Optional · string

metadata.name

Required · string

Project-local identity, validated by the resource kind; remains static during discovery.

spec

Required · object

The build inputs, registry destination, and common unit policy.

Unknown fields are rejected.

spec.approval

Optional · string or object

Whether executions need an invocation’s approval.

Match one or more variants:

Variant 1

Type: string

Allowed values: "auto" · "manual"

Variant 2

Type: object

When a unit’s executions need an invocation’s approval.

Written as auto (the default), manual (short for {mode: manual, bind: desired}), or {mode, bind, requireDigest}.

spec.approval.bind

Required · string

What an approval authorizes: one execution of the desired document, or the changes a reviewed plan showed.

Allowed values: "desired" · "plan"

spec.approval.mode

Required · string

auto executes without approval; manual waits for --approve.

Allowed values: "auto" · "manual"

spec.approval.requireDigest

Optional · boolean

Refuse approvals without a change digest, for bind: plan.

spec.attestations

Optional · array

Attestations of the unit’s receipts: names its kind produces itself, or entries with from: external that only nyl attest supplies.

spec.attestations[]

Required · object

One attestation a unit’s receipts can carry.

Unknown fields are rejected.

spec.attestations[].from

Optional · string or null

external for an attestation only nyl attest supplies; omitted for one the kind produces itself.

Allowed values: "external" · null

spec.attestations[].name

Required · string

Attestation name, such as healthy.

spec.buildArgs

Optional · object

Build arguments, with references resolved before execution. Values must resolve to scalars.

Additional keys may contain any value.

spec.builder

Optional · string or null

Runner’s Buildx builder; excluded from the execution key.

spec.cache

Optional · object or null

Buildx cache imports and exports; excluded from the execution key.

Unknown fields are rejected.

spec.cache.from

Optional · array

Buildx cache import specifications passed as --cache-from.

default: []

spec.cache.from[]

Required · string

spec.cache.to

Optional · array

Buildx cache export specifications passed as --cache-to.

default: []

spec.cache.to[]

Required · string

spec.context

Required · object

Main build context, following the common Git source and local path rules.

spec.context.commit

Optional · string or null

Full 40-character lowercase commit ID that is read, refreshed by nyl update source-locks.

spec.context.path

Optional · string or null

Path in the repository. In this repository it follows the local path rule: relative to the directory containing nyl.toml, may begin with .. segments, or starts with / to name a path from the Git worktree root, and never leaves the worktree. In a remote repository it is relative to the checkout root, with an optional leading /.

spec.context.repository

Optional · object or null

Inline repository coordinates to read from. Mutually exclusive with repositoryRef.

Unknown fields are rejected.

spec.context.repository.repoURL

Required · string

Git read URL. Source checkouts never publish to this repository.

spec.context.repositoryRef

Optional · object or null

Project-local gitops.nyl/v1 GitRepository to read from. Mutually exclusive with inline repository.

Unknown fields are rejected.

spec.context.repositoryRef.name

Required · string

Project-local name of the referenced resource; its kind and API group are determined by the containing field.

spec.context.revision

Optional · string or null

Human-readable branch or tag that nyl update source-locks resolves.

spec.contexts

Optional · object

Named directories or digest-pinned image references, passed with --build-context.

spec.contexts[key]

Optional · alternatives below

A directory source or an image reference for a named Buildx context.

Match one or more variants:

Variant 1

Type: object

An image context. Its reference can be supplied by a fromUnit artifact binding.

Unknown fields are rejected.

spec.contexts[key].image

Required · any value

A digest-pinned image reference or a fromUnit artifact binding.

Variant 2

Type: object

A directory or file in a Git repository: this repository when no repository is named, otherwise a remote one, optionally pinned to a commit.

spec.contexts[key].commit

Optional · string or null

Full 40-character lowercase commit ID that is read, refreshed by nyl update source-locks.

spec.contexts[key].path

Optional · string or null

Path in the repository. In this repository it follows the local path rule: relative to the directory containing nyl.toml, may begin with .. segments, or starts with / to name a path from the Git worktree root, and never leaves the worktree. In a remote repository it is relative to the checkout root, with an optional leading /.

spec.contexts[key].repository

Optional · object or null

Inline repository coordinates to read from. Mutually exclusive with repositoryRef.

Unknown fields are rejected.

spec.contexts[key].repository.repoURL

Required · string

Git read URL. Source checkouts never publish to this repository.

spec.contexts[key].repositoryRef

Optional · object or null

Project-local gitops.nyl/v1 GitRepository to read from. Mutually exclusive with inline repository.

Unknown fields are rejected.

spec.contexts[key].repositoryRef.name

Required · string

Project-local name of the referenced resource; its kind and API group are determined by the containing field.

spec.contexts[key].revision

Optional · string or null

Human-readable branch or tag that nyl update source-locks resolves.

spec.deletionPolicy

Optional · string or null

What happens to the unit’s resources when it leaves the ownership set. Default Teardown where the kind supports teardown, else Retain.

Allowed values:

Value	Meaning
"Teardown"	Tear the resources down, after --allow-teardown.
"Retain"	Leave the resources in place.
null

spec.dependsOn

Optional · array

Units that must have a current receipt first, for ordering without a data reference.

spec.dependsOn[]

Required · string

A unit that must have a current receipt before this one runs: a name, or an entry naming another declared environment or stronger evidence.

Match one or more variants:

Variant 1

Type: string

A unit of the same environment.

Variant 2

Type: object

A unit, optionally of another declared environment, with required evidence.

Unknown fields are rejected.

spec.dependsOn[].attestations

Optional · array

The producer’s attestations to require, instead of all it declares.

spec.dependsOn[].attestations[]

Required · string

spec.dependsOn[].environment

Optional · string or null

Another declared environment; default this one.

spec.dependsOn[].evidence

Optional · string or null

Required evidence: published (a current receipt, the default) or attested.

Allowed values:

Value	Meaning
"published"	A current receipt.
"attested"	A current receipt whose required attestations pass.
null

spec.dependsOn[].unit

Required · string

The producing unit.

spec.dockerfile

Optional · string

Dockerfile relative to the main context, default Dockerfile; cannot leave the context.

default: "Dockerfile"

spec.enabled

Optional · boolean

Evaluated after rendering; false leaves the environment’s ownership set, which deletes the unit under its deletionPolicy.

spec.env

Optional · object

Variables and secrets admitted into the unit’s otherwise empty tool environment.

Unknown fields are rejected.

spec.env.passthrough

Optional · array

Names of runner environment variables copied as they are.

spec.env.passthrough[]

Required · string

spec.env.secrets

Optional · object

Variables read from the project’s secrets provider, by variable name and secret key. An object or array secret is passed as compact JSON.

spec.env.secrets[key]

Optional · string

spec.outputs

Optional · object

Declared outputs, for kinds that let units declare them. Only declared outputs are recorded.

spec.outputs[key]

Optional · object

One declared output: a type from the Release input type set.

Unknown fields are rejected.

spec.outputs[key].description

Optional · string or null

Documentation, surfaced in inspection.

spec.outputs[key].sensitive

Optional · boolean

Validated but never persisted, and never referenceable.

spec.outputs[key].type

Required · string

Value type: string, integer, number, boolean, object, or array.

Allowed values:

Value	Meaning
"string"	A JSON string.
"integer"	A JSON integer; numbers with a fractional part are rejected.
"number"	Any JSON number.
"boolean"	true or false.
"object"	A JSON object. Only the top-level type is checked.
"array"	A JSON array. Only the top-level type is checked.

spec.platforms

Optional · array

Target platforms, such as linux/amd64. Omitted uses the builder’s platform.

spec.platforms[]

Required · string

spec.registryAuth

Optional · object

Registry host to username/password secret keys. Values never enter state or execution keys.

spec.registryAuth[key]

Optional · object

Secret keys for one registry; the runner never reads undeclared credentials.

Unknown fields are rejected.

spec.registryAuth[key].passwordSecret

Required · string

Project secret key containing this registry’s password or access token.

spec.registryAuth[key].usernameSecret

Required · string

Project secret key containing this registry’s username.

spec.repository

Required · string

Registry repository without a tag or digest, such as registry.example.com/team/web.

spec.tags

Optional · array

Extra moving tags in this repository. Consumers use the immutable artifact reference.

spec.tags[]

Required · string

spec.target

Optional · string or null

Optional Dockerfile build stage.

spec.timeout

Optional · string or null

Deadline for one execution, teardown, or verification, at most 7d. Default per kind.

pattern: "^(?=.)([0-9]+d)?([0-9]+h)?([0-9]+m)?([0-9]+s)?$"