opschain templates version upsert

templates

opschain templates version upsert <project>/<code> --version <v> [--git-rev <rev>] [--description <text>] [--fetch] [--float] [--pack <name>=<version>] [--ignore-in-use]

One write verb for a template version's content: it creates the named version when it does not exist (pinned to --git-rev, which a first create requires), and updates it when it does. At least one of --git-rev, --description, --float, --pack or --fetch must be passed — an empty upsert is refused.

What each input does on an existing version:

• --git-rev repins the version to a different branch, tag or commit of the template's Git remote.
• --description re-describes it (an empty value clears it — the flag is sent whenever given).
• --fetch re-resolves the stored revision against the remote, so a floating branch picks up new commits without repinning. The fetch also re-resolves the version's pack pins — every unversioned declaration seals the estate default again — except the explicit pins set with --pack, which it keeps (re-validated as installed).
• --float marks the version as following its revision on every fetch of its Git remote — the server's periodic fetch (the remote's effective periodic_fetch_interval, 900 s unless overridden) repins it whenever the branch tip moved, rolling its assets and refreshing their catalogs the way --fetch does, and records info:template_version:rev_repinned (--float=false unmarks it; the flag is sent only when given). Not allowed while the version is locked, and refused for a break-glass account (the repin runs as the version's creator, and break-glass identities are interactive-only — pin the revision, or create the version as an everyday user). opschain docs resources/git_remote describes the sweep.
• --pack <name>=<version> sets the version's explicit pin for an installed pack its .opschain/packs.yaml declares without version:: every mount of that pack seals the named installed version, recorded as decided_by: explicit in the version's sealed_packs, and later fetches of the revision keep the choice. Repeatable. --pack <name>= (empty version) clears the explicit pin back to the estate default — the pack's admin pin, else the highest installed version. The repin is audited on the version (info:template_version:pack_repinned), and with --ignore-in-use the assets pinned to the version refresh their action catalogs the way a fetch refreshes them.

Lifecycle guards: a locked or archived version only accepts its own unlock/unarchive, so upserting one — pins included — is refused. Changing or fetching the revision, or the pack pins, of a version that assets are pinned to is refused; --ignore-in-use overrides that refusal and rolls the pinned assets onto the newly resolved commit.

Flags

Flag	Meaning
--version <v>	The version string, e.g. 1.2.0 (required).
--git-rev <rev>	The branch, tag or commit to pin (required on first create).
--description <text>	The version's description.
--fetch	Re-resolve the stored revision against the Git remote.
--float	Follow the revision: every fetch repins to its current commit.
--pack <name>=<version>	Explicit pack pin for an installed pack declared without version: (repeatable; <name>= clears it back to the estate default).
--ignore-in-use	Override the in-use refusal: repin even while assets use this version, rolling them onto the new commit.

Exit codes

Code	Meaning
0	Upserted — prints upserted version <v> of <project>/<code> (<state>, git rev <rev>).
1	The template was not found, or the server refused (locked/archived version, in-use revision or pin change, unresolvable revision, a pack pin refusal below).
2	Usage error — empty upsert, missing required flag, malformed --pack, malformed address, no server target.

Named errors

• nothing to upsert — pass --git-rev, --description, --float, --pack and/or --fetch — exit 2.
• --pack expects <name>=<version> (or <name>= to clear the explicit pin), got "<value>" — exit 2.
• required flag(s) "version" not set — exit 2.
• expected <project>/<template-code>, got "<arg>" — exit 2.
• template "<code>" not found in project "<project>" — exit 1.
• Template version cannot be modified as the version is currently locked — exit 1; unlock first (the lock is the seal).
• pack <name> is set in .opschain/packs.yaml: template <code> declares mount <mount> with version: <v>, which seals it — a per-version pin cannot move it … — exit 1; change the declaration in the template repository instead.
• pack <name> version <v>: the pack is not installed — exit 1; install it (opschain admin packs install) or name an installed version.
• pack <name> is not declared by the version's commit <sha> … — exit 1; the pin names a pack the version's packs.yaml declares with installed:.
• Template version's pack pins cannot be changed as the version is currently in use — exit 1; pass --ignore-in-use to repin and roll the assets.
• pack <name> version <v> — this template version's explicit pin for mount <mount> — is no longer installed; … — exit 1, on --fetch: set another installed version or clear the pin before fetching.

Examples

Create a version pinned to a tag:

opschain templates version upsert demo/web_stack --version 1.1.0 --git-rev v1.1.0
upserted version 1.1.0 of demo/web_stack (available, git rev v1.1.0 (8c04e7b))

A floating development version that tracks a branch:

opschain templates version upsert demo/web_stack --version edge --git-rev main --float

Pick up the branch's new commits, rolling the assets pinned to it:

opschain templates version upsert demo/web_stack --version edge --fetch --ignore-in-use

Move this one version onto a newer installed pack version while the estate's admin pin stays where it is — the choice survives later fetches:

opschain templates version upsert demo/web_stack --version 1.1.0 --pack opschain-pack-azure=0.2.5
upserted version 1.1.0 of demo/web_stack (ready, git rev v1.1.0 (8c04e7b))

Clear the explicit pin so the version follows the estate default again:

opschain templates version upsert demo/web_stack --version 1.1.0 --pack opschain-pack-azure=

See also

• opschain docs cli/templates-version-lock — freeze a version once it is proven.
• opschain docs cli/templates-re-resolve — roll a pack version across every template in one verb (with --version, the same explicit pin on every cut version).
• opschain docs cli/admin-packs-pin — the estate default an unpinned mount seals.
• opschain docs cli/templates-assign — move assets between versions.
• opschain learn 3.3 — the guided tour.