Promote an immutable artifact version

Promotion moves a stage label such as staging or production to an existing immutable artifact version. It copies no payload bytes and does not change the version manifest.

Inspect versions and labels

crab artifacts show fraud-model --json
crab artifacts history fraud-model --json

Record the current version assigned to the target stage. A version is a content-addressed identity; the stage is a mutable human-facing label.

Promote with compare-and-swap

crab artifacts promote \
  fraud-model \
  <new-version> \
  production \
  --expected <current-version> \
  --json

Automation should pass --expected <CURRENT_VERSION>. A concurrent change then fails instead of silently overwriting the label. Promotion records the prior value and timestamp in the remote (or local, when no remote is configured) audit history and copies no artifact bytes.

Verify canonical state

Use crab artifacts show <NAME> to inspect versions and labels without hydrating payloads. With a configured Crab remote, the stage label uses a remote CAS write and another clean clone observes the same canonical state. Artifact GC retention remains conservative: old immutable versions are not removed automatically.

crab artifacts show fraud-model
crab artifacts history fraud-model

The new stage mapping and a promotion event with the prior value are the completion evidence. If compare-and-swap fails, reread the label and decide whether the concurrent promotion should remain; do not retry with a guessed expected version.

Use labels for environments, not identity

Consumers that require an immutable result should store the version ID they resolved, even when discovery began from a stage label. A later promotion can move production without changing either version's manifest. This separation lets operators roll a label forward or back while audit records retain the exact sequence of prior values.

Before promotion, retrieve the candidate by version in a validation environment and run application-level checks. Registry hash verification proves payload identity, but it does not prove model quality, schema compatibility, or rollout safety. Promotion should follow those domain checks rather than replace them.

Choose promotion instead of creation