Environment

gitops.nyl/v1

Orchestration Resources · Download JSON Schema · Usage guide

A named place that units are reconciled into, with its own state.

An Environment selects units by their literal labels and gives their templates its values. The selected, enabled units are its ownership set: a unit that leaves the set is deleted under its deletion policy.

When needed

To reconcile units with nyl reconcile -e <environment>.

If omitted

No orchestration happens; rendering and publication work as before.

Example

apiVersion: gitops.nyl/v1
kind: Environment
metadata:
  name: production
spec:
  protectedRefs:
    - main
  state:
    repositoryRef:
      name: deploy
  unitSelector:
    matchLabels:
      stage: production
  values:
    target: production

Fields

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

Unknown fields are rejected.

apiVersion

Required · string

API group and version defining this resource.

const: "gitops.nyl/v1"

kind

Required · string

Resource kind within the API group.

const: "Environment"

metadata

Required · object

Resource identity and metadata.

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

Optional · object

Configuration for this resource.

default: {"state":{},"unitSelector":{}}

Unknown fields are rejected.

spec.admission

Optional · string or null

CI deployment admission: required makes state-writing runs use the source of the current admission. Omitted, the group’s, else off.

Allowed values: "off" · "required" · null

spec.allowUnprotectedSource

Optional · boolean or null

Whether runs may use source commits outside protectedRefs. Omitted, the group’s, else false.

spec.attestations

Optional · array

Environment-wide attestations, recorded with nyl attest for the environment’s current state.

spec.attestations[]

Required · string

spec.driftRepair

Optional · string or null

Whether reconcile repairs drift by itself: converge executes units whose latest drift observation is drifted again (units not safe to re-run await approval); manual leaves them drifted until --reapply. Omitted, the group’s, else converge.

Allowed values:

Value	Meaning
"converge"	The next reconcile executes drifted units whose recovery policy is converge again; a drifted unit that is not safe to re-run awaits approval.
"manual"	Reconcile repairs no drift by itself: drifted units stay drifted until nyl reconcile --unit <unit> --reapply --reason <text>.
null

spec.protectedRefs

Optional · array or null

Refs that pinned commits and run source commits must be reachable from. Omitted, the group’s, else each repository’s default branch.

spec.protectedRefs[]

Required · string

spec.source

Optional · object or null

The source commit runs use. Omitted, the commit of the worktree a run starts from.

Unknown fields are rejected.

spec.source.commit

Optional · string or null

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

spec.source.fromPromotion

Optional · object or null

The source commit recorded by the newest promotion on a path; excludes the other fields.

Unknown fields are rejected.

spec.source.fromPromotion.path

Optional · string or null

The PromotionPath that supplies the source. Mutually exclusive with paths.

spec.source.fromPromotion.paths

Optional · array

Several PromotionPaths; the newest record on any of them wins. Mutually exclusive with path.

spec.source.fromPromotion.paths[]

Required · string

spec.source.fromPromotion.promoted

Optional · any value

The record nyl promote writes here with record: source, never by hand.

spec.source.fromPromotion.record

Optional · string or null

Where the PromotionRecord lives: state (default) or source.

spec.source.repository

Optional · object or null

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

Unknown fields are rejected.

spec.source.repository.repoURL

Required · string

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

spec.source.repositoryRef

Optional · object or null

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

Unknown fields are rejected.

spec.source.repositoryRef.name

Required · string

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

spec.source.revision

Optional · string or null

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

spec.state

Optional · object

Where the environment’s state lives.

default: {}

Unknown fields are rejected.

spec.state.admissionRef

Optional · string or null

Ref of the deployment admission record. Default the desired ref.

spec.state.coordinationRefPrefix

Optional · string or null

Prefix, ending in /, of the leases, runs, and signals refs. Default refs/nyl/.

spec.state.desiredRef

Optional · string or null

Ref of the desired state. A short name is a branch. Default nyl/<environment>/desired.

spec.state.observedRef

Optional · string or null

Ref of the observed state; may equal desiredRef. Default nyl/<environment>/observed.

spec.state.path

Optional · string

Directory of the environment’s state within its refs, so several environments can share one ref. Default the root.

spec.state.repository

Optional · object or null

Inline repository coordinates holding the state. Mutually exclusive with repositoryRef.

Unknown fields are rejected.

spec.state.repository.publishURL

Optional · string or null

Optional Git write URL. Publication uses repoURL when omitted.

spec.state.repository.repoURL

Required · string

Credential-free Git read URL used by renderers and generated Applications.

spec.state.repositoryRef

Optional · object or null

GitRepository holding the state, read through its repoURL and written through its publishURL. Mutually exclusive with repository. Omitted with repository: the group’s, else the checkout’s origin, else the local repository.

Unknown fields are rejected.

spec.state.repositoryRef.name

Required · string

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

spec.unitSelector

Optional · object

Matches literal unit metadata.labels across all unit kinds. An empty selector selects every unit.

default: {}

Unknown fields are rejected.

spec.unitSelector.matchLabels

Optional · object

Exact label matches, combined with AND. An empty map selects every ApplicationGroup.

spec.unitSelector.matchLabels[key]

Optional · string

spec.values

Optional · object

Values unit templates see as values, merged recursively over the values of the EnvironmentGroup selecting this environment.

Additional keys may contain any value.