Environment version Pins

A Pin protects the exact Module Version already active in one Environment. Pinning in the Orchestrator never deploys another version, aligns Environments or changes a Module’s Default.

When to pin #

Pin the current version when an application must remain on it while the platform moves forward. An Environment needs a trustworthy successful Deployment and no active mutating deployment lease. Running or Unreconciled Environments must settle or recover before they can be pinned.

The current version may be Default, Proposed or Deprecated. An archived Module may also be pinned in an Environment already using it. This preserves existing use; it does not allow another Environment to adopt the archived Module or a Deprecated version. A Defective version requires the separate module.version.pin-defective capability and explicit confirmation of its UUID.

An active Pin overrides implicit Default resolution. Later deployments must preserve the pinned version and reject explicit selection of a different one. Pins have no expiry and survive changes to the Default, creator access and Module archival. If the pinned version becomes Defective, the Pin stays active, but carrying that version forward needs the restricted capability and confirmation. Stellwerk never auto-unpins or starts recovery on your behalf.

Create and inspect a Pin #

In the Console, inspect Module or Version usage to identify the Environment’s current version. Pin actions in the Environment and Project views show the exact version and require a reason. Production impact is highlighted before submission.

The CLI uses immutable IDs from the Project, Environment, Module catalogue and current-version responses. Save these IDs and the reason in pin.json:

{
  "project_uuid": "11111111-1111-4111-8111-111111111111",
  "environment_uuid": "22222222-2222-4222-8222-222222222222",
  "module_uuid": "33333333-3333-4333-8333-333333333333",
  "version_uuid": "44444444-4444-4444-8444-444444444444",
  "reason": "Keep the current data tier during the checkout migration"
}

Replace the illustrative UUIDs with the actual current identities, then run:

octl create module-version-pin --set-json=@pin.json \
  --idempotency-key=checkout-data-tier-pin
octl get module-version-pins --environment-uuid="$ENVIRONMENT_UUID"
octl get module-version-pin "$PIN_ID" -o json
octl get module-version-pin-history "$PIN_ID"

Bulk actions are frozen snapshots #

A Project bulk Pin freezes an explicit set of Environment UUIDs. Each Environment keeps its own current version, so the result can contain several versions of the same Module. The Console previews the complete set grouped by version, including Production and permission or eligibility problems.

Bulk Pin, Unpin and Discard are atomic: you must have permission for every selected Environment, and all of them must be eligible. Otherwise, nothing changes. Existing Pins to the same exact version already satisfy the request. An Environment created later remains unpinned; select it explicitly in another operation if it needs protection.

For API automation, first submit the explicit set to POST /orgs/{orgId}/module-version-pins/bulk-preview. Submit the same set, returned fingerprint as preview_fingerprint, mandatory reason and an Idempotency Key to POST /orgs/{orgId}/module-version-pins/bulk. The corresponding commands are octl get module-version-pin-bulk-preview and octl create module-version-pin-bulk, both accepting --set-json=@file.json. If the preview is stale, refresh it and review the new result before applying. Do not substitute a different set of Environments.

Notes and removal #

The creation reason is immutable. Add an explanatory note instead of editing it:

octl create module-version-pin-note "$PIN_ID" \
  --note="Application migration now scheduled for the next release window" \
  --idempotency-key=checkout-pin-schedule-note

A note records a new actor, time and revision, but does not change the Pin’s version, state or activation boundary. It neither extends nor weakens protection and does not invalidate approvals bound to that unchanged boundary.

To remove an active Pin, read its latest resource_version, set PIN_REVISION to that value and run:

octl update module-version-pin "$PIN_ID" --action=unpin \
  --expected-version="$PIN_REVISION" \
  --reason="Checkout migration complete; allow the next deployment to advance" \
  --idempotency-key=checkout-data-tier-unpin

Unpin affects future resolution only. It does not create a Deployment or resume a deferred operation. Pin control is scope-based: any currently authorised principal may remove another person’s Pin. The creator has no special rights after losing access.

States and optional add-on operations #

An add-on may ask the Orchestrator to override a Pin for one specific operation. Success makes the Pin Overridden; failure or cancellation restores Active protection. An unresolved deployment keeps the lock even after a restart. Time is never proof of a completed operation.

An authorised Discard pin permanently action removes an Overridden Pin without changing the Environment and prevents later rollback restoration. Otherwise, only a successful rollback by the exact owning operation to the exact pinned version can restore it. A failed rollback, version mismatch or later explicit removal cannot recreate the Pin.

Permissions and deletion #

module.version.pin, module.version.pin-note and module.version.unpin are independent capabilities granted at organisation, Project or Environment scope. Organisation grants include descendant scopes. Bulk commands require access for every Environment. Add-on rights never imply direct Unpin rights.

Normal Environment deletion previews its Pins and related add-on resources. Active and Overridden Pins do not prevent authorised deletion, but an Override Pending operation must finish or be cancelled first. Successful deletion moves its remaining Pins to the terminal Removed state and retains their audit history.