Skip to content

Versions & lifecycle

Each Configuration is a sequence of immutable Versions. Versions move through three states:

Draft → Published → Archived

Draft

Editable. Optimistic concurrency via row-version means concurrent edits surface a "someone else updated this" prompt — the loser gets their copy back to fix and re-save.

A configuration can have multiple drafts (e.g. one in flight, one in review). Drafts can be discarded.

Published

A Publish action takes a draft, runs validation + lint one more time, and on success moves the row to Published. The row becomes immutable — the YAML, the hash, and the metadata are frozen.

Every Published version has a content hash; that hash is what flows over the wire to agents. Agents already running that exact hash are not asked to re-apply.

Archived

An Archive action retires a Published version. Archived versions:

  • still validate against (so old rollouts referencing them remain valid),
  • do not appear in the default version picker — pickers default to "Published only",
  • can be unarchived by Admin (audit-logged).

You typically archive after a successor version has been live across the fleet for long enough that there is no plausible rollback.

Hashes

Each version has:

  • Content hash — SHA-256 of the YAML, used for OpAMP-side deduplication.
  • Semantic hash — SHA-256 of the normalised component model. Two versions with identical semantics but different formatting share the same semantic hash. Used by the auto-apply pipeline to skip no-op rollouts.

Both are surfaced on the Versions list with a copyable short form.

Filtering

The Versions list filters by:

  • Status — Draft / Published / Archived.
  • Author — actor who saved the draft / published.
  • Hash prefix — paste a short hash to find a specific version.
  • Date range.

Comparison

Pick any two versions in the list, click Compare. See Diffs.

Source

Each version has a Source chip:

  • UI — saved through the editor.
  • Git — imported from a registered Git source. The chip links to the source file at the imported commit SHA.
  • API — created via the REST API.

For Git-sourced versions, the editor is read-only — the source of truth is the Git repo.

Rollouts and version pinning

A rollout pins to exactly one Published version of a configuration. Once started, the version cannot be changed mid-flight; instead, abort the rollout and start a new one.

This pinning is intentional — a rollout is a contract between an operator and a fleet about a specific change, not a moving target.

Auto-apply

When a configuration has a default group and a new version is published, the auto-apply service queues a rollout for that group. The rollout uses the group's default strategy (Rollouts); auto-apply does not bypass policy or health gates.

Disable auto-apply per group in the Group settings if you prefer explicit operator-driven rollouts.