Release

Releases are a point-in-time snapshot of configuration stored as an OCI image. A Release bundles the Units in a Space that are not Unreleasable, for the Space's release Target (its ReleaseTargetID), capturing each Unit either at its head Revision or at a specified tagged one. The ID of that Target is stored on the Release (TargetID), both as the record of what the configuration was published for and as the basis for pull authorization.

Each Release carries a ReleaseNum — a sequence number that increments per Space — along with two OCI digests: ManifestDigest for the image manifest and Digest for the compressed bundle layer. Each Release also either creates a Tag or uses the one provided, associating it with the bundled Revisions. A Unit the provided Tag marks no Revision of is left out of the bundle and listed in the Release's SkippedUnits when it has never been released, and refuses the publish when it has, since a bundle without it would delete it from the Target. UnitCount is the number of Units bundled.

A Release published for a ChangeOrder is bundled at the ChangeOrder's release Tag, records the ChangeOrder in ChangeOrderID, and must satisfy the release prerequisites of the ChangeOrder's ChangeWorkflow, such as required approvals. Its PriorRevisions says whether it may also deliver a Unit's revisions from before the change. Naming the release Tag without the ChangeOrder publishes for the ChangeOrder all the same. A publish can be a dry run, which reports the Release it would publish, or why it would be refused, and publishes nothing.

The OCI URL for each Space's Releases is oci://<host>:<port>/space/<space-slug> on the server's OCI endpoint, with either the latest OCI tag or a specific digest. latest refers to the most recently published Release for the Space's current release Target. This URL is used by OCI clients, such as ArgoCD or FluxCD, to consume the image and apply the configuration accordingly. Pulling requires View permission on the Release, which is derived from the Target: anyone with ViewChildren permission on it may pull. See Releases and OCI delivery.

A Release's bundle and everything describing it are fixed when it is published. What can change afterwards is its Labels, Annotations, DeleteGates and Permissions, and its LiveStatus: what the tool deploying it, such as argobot for Argo CD, reports about it running. See live resources. Edit on a Release is derived from the Target as View is: EditChildren on the Target grants it, which is what lets that tool write the status. Changing a Release's Permissions or DeleteGates needs Manage on the Release itself.

Publishing, withdrawing and deleting a Release each change what the Target runs, so each requires TargetEditChildren on the Release's Space, which the tool reporting live status does not need. Publishing requires nothing on the Target itself: making it the Space's release Target required Use on it and Edit on the Space and on each Unit it releases. Publishing without naming a Tag also creates one, which requires CreateChildren on the Space, and publishing for a ChangeOrder requires Use on it. See authorization.

A Release can be withdrawn, which takes it out of service: it is no longer served from the OCI endpoint, while the Release itself is retained as the record of what was published. Deleting a Release removes it and its stored bundle. A Destroy Gate on any Unit in the bundle blocks withdrawal until it clears. See Publishing Releases.