Publish and manage versions

Branch commits are for authoring. Versions are what labs consume: an immutable, semver-numbered snapshot of a module’s committed content, recorded in the registry.

A module can only be added to a lab once it has at least one published version, so publishing a version is the step that makes a module usable.

Publish a version

1. Open the module and make sure the branch you want to release from is selected, and that everything you want in the release is committed to it.
2. Outside edit mode, click Publish version in the editor header.
3. In Version, enter the version number. The field is prefilled with the next patch of the highest version already published, or 1.0.0 if this is the first. The dialog checks the number as you type and keeps Publish disabled until it is valid.
4. Click Publish.

Caution

A version is cut from the committed content on the branch. Publish version is not shown while you are in edit mode, so an open edit session can never end up in a release by accident. If your changes belong in the release, click Publish changes to commit them to the branch first, then publish the version.

Version number rules

Rule	Detail
Strict semver	Exactly MAJOR.MINOR.PATCH, all three parts, all numeric – 1.4.0, not 1.4.
No leading v	1.4.0, not v1.4.0.
No prerelease or build suffix	1.4.0-rc.1 and 1.4.0+build.7 are refused.
Size limits	At most 20 characters in total, and each part at most 2147483647.
Must be new	A number is spent once at an address, permanently. See Numbers are never reissued.

A version is not a Git tag. Instruqt does not read versions from repository tags and does not create tags when you publish, so however the repository is tagged is entirely independent of this. That is deliberate: a force-pushed tag would otherwise arrive as new content under a number that had already been published, and a pin resolving to the same content forever is what everything else here rests on.

A version is immutable. To change what a version’s content is, publish a new number – there is no way to amend one.

What to bump

Consuming labs write constraints like ~> 1.4, and a constraint only works if authors number releases honestly. The usual semver rules apply, read from the point of view of a lab that depends on you:

• Patch (1.4.0 → 1.4.1) – a fix that changes nothing about the module’s interface. No new variables, no removed outputs, no behaviour a lab was relying on.
• Minor (1.4.1 → 1.5.0) – something added. A new variable with a default, a new output, a new sandbox resource. A lab on ~> 1.4 will pick this up without being touched, so it has to be safe.
• Major (1.5.0 → 2.0.0) – anything a consumer has to react to. A removed or renamed variable or output, a variable that loses its default, or a change in what a resource does.

The Versions page

Click the tag icon in the module editor header, or View in the Versions section of the module’s Overview.

Every version ever published from the module is listed here, newest first, including revoked and deleted ones. Each row shows:

• The version number.
• When it was published.
• The commit it was cut from, linking into Change history.
• A Revoked or Deleted badge where one applies. Hover the badge for the date.

The ••• menu on each row offers Revoke, Restore, and Delete.

Revoke a version

Revoking withdraws a version from being offered. It stops appearing in listings, and no version constraint will select it. A lab that pins it exactly still resolves it, so nothing that already depends on it stops working.

1. On the Versions page, click ••• on the version and select Revoke.
2. Click Revoke version.

This is the ordinary way to stop people picking up a release – a version you would rather nobody new adopted, but that you have no reason to break. It is reversible.

Restore a version

Restoring undoes a revoke. The version reappears in listings and constraints can select it again. Labs pinning it exactly are unaffected, because they never stopped resolving it.

1. On the Versions page, click ••• on the version and select Restore.
2. Click Restore version.

Restore undoes revoking and nothing else. A deleted version cannot be restored.

Delete a version

Deleting is permanent, and it breaks labs on purpose. Any lab pinning the version fails to resolve rather than runs – at its next session, in any team, including teams whose usage you cannot see.

1. On the Versions page, click ••• on the version and select Delete.
2. Optionally, fill in Reason. It is shown to whoever hits the failed resolution, so they learn why rather than seeing a missing module. Maximum 256 characters.
3. Type the version number to confirm.
4. Click Delete version.

Deleting a version is refused while the module is Protected. Clear Protected in Project settings → General first.

Danger

Revoke unless the content genuinely has to come down. The canonical reason to delete is a leaked credential baked into the published content – something that must not run anywhere, where breaking the labs that pin it is the point rather than the cost.

What each state means

State	Listed	Selectable by a constraint	Resolves an exact pin	Reversible
Published	Yes	Yes	Yes	–
Revoked	No	No	Yes	Yes, with Restore
Deleted	No	No	No – resolution fails	No
Restored	Yes	Yes	Yes	–

Revoked and deleted versions stay on the Versions page in both cases. They leave the listings a consumer sees, not your own record of them.

Numbers are never reissued

A version number is recorded against the module’s team-slug/module-slug address, not against the module row. Once 1.4.0 has been published at an address it is spent there permanently – including after the module is deleted and a new module is created at the same freed address.

This is what makes a pin trustworthy. acme/postgres at 1.4.0 names one archive forever, so a lab that resolved it once will never silently resolve to different content.