skip to content

Versioning & Immutability

Pipelines are reproducible only if a published version never changes. Interviewers ask how repositories enforce that, where mutable tags and snapshots fit, and what breaks when they slip.

on this pageshow

questions

5

In a package repository, why must a published release version never be overwritten with new contents, and how do servers enforce that?

level: juniorimportance: must knowfreq 70%

answer

  1. one name, one set of bytes
  2. caches keep the first copy
  3. server refuses a repeat upload
  4. npm never reuses a number

basics

~20 s

A release version promises that one name always means the same bytes. Overwriting it lets two builds of one version differ, so servers holding releases refuse a second upload and fixes ship as new versions.

solid answer

~50 s

Every consumer treats `name@version` as a fixed identity: proxy repositories and build caches keep the first copy they fetched, and lockfiles or build logs record its hash. Overwrite a release and the world splits: machines holding the old bytes keep them, fresh machines get the new ones, and the same version builds different code. Servers enforce the rule at upload time. NuGet's publish API answers `409` when the ID and version already exist; nuget.org always rejects, though the protocol says other package sources may allow replacing. The npm public registry never accepts a `package@version` twice, even after an unpublish. Repository managers apply it per repository: a release repository is set to refuse a second upload to an existing path, while a snapshot repository deliberately takes new builds. A broken release is fixed by publishing a new version.

go deeper

for a junior

Recall the promise: one version, one set of bytes, forever. Know that a broken release is fixed by publishing a new version, never by uploading over the old one.

for a middle

Explain why an overwrite splits the world: caches and lockfiles keep the old bytes while clean machines fetch the new. Name how npm, NuGet and a release repository each refuse a second upload.

for a senior

Show you check enforcement per server rather than assume it: some sources replace a duplicate, OCI tags move by default, and a sidecar checksum cannot prove a release stayed unchanged.

for a principal

Treat immutability as an organisation-wide guarantee: decide which repositories and registries must refuse overwrites, who may change that setting, and how a bad release is withdrawn without reusing its number.

## What a published version promises A **release version** such as `2.4.1` is a name that a repository hands out to every consumer. The whole delivery chain assumes that name maps to **one fixed set of bytes, forever**. Build tools, proxy repositories, CI caches, lockfiles and deployment records all key on it. A version that can change is not a version; it is a moving label wearing a version's clothes. The idea is called **version immutability**: once a repository has served a version, the content under that version must never change. It is enforced on the **server side** (the repository or registry refuses the write), not by the client being careful. ## Why overwriting a release breaks things Overwriting does not replace the old bytes everywhere. It replaces them in **one** place, while copies of the old bytes keep living elsewhere: - **Caches keep the first copy.** A proxy repository at another site, a CI runner's local cache and a developer laptop all fetched the original file and will keep serving it, so different machines now hold different bytes under one name. - **Recorded hashes stop matching.** A lockfile's integrity value or a checksum logged by a build was computed from the old bytes; a clean machine now downloads content that fails, or silently differs from, that record. - **Builds stop being reproducible.** Rebuilding last month's release from the same inputs no longer gives the same output, because one input changed under a constant name. - **Forensics break.** When an incident asks "what was in 2.4.1?", there are now two honest answers. ## How servers enforce it Enforcement differs per format and per server, which is why it has to be checked rather than assumed: | Server | What happens on a second upload of an existing version | |---|---| | npm public registry | Rejected. A `package@version` can never be used again, even after it was unpublished. | | NuGet v3 publish API | `409`: a package with that ID and version already exists. nuget.org always rejects; other package sources may allow replacing. | | Release repository in a repository manager | Refused when the repository is configured to forbid redeploying an existing path, the normal setting for releases. | | Snapshot repository | Accepted by design: each build gets a new timestamped file. | | OCI registry tag | Moved by default: a tag is a pointer, and freezing it is an extra registry setting (Harbor's tag immutability rules, for example). | On the npm public registry, the rule survives deletion: npm's unpublish policy says that once a name and version have been used, they can never be used again, so a new version is required even if the old one was unpublished. That closes the loophole of "delete it and push it again". Repository managers such as Artifactory and Nexus Repository separate **release** repositories from **snapshot** repositories. In Nexus Repository a hosted maven2 repository carries a **version policy** (release or snapshot); in Artifactory a local repository has **Handle Releases** and **Handle Snapshots** switches. The release side is where the no-overwrite rule lives. ## The deliberate exceptions Two kinds of names are *meant* to move, and they do not weaken the rule: 1. **Snapshots** such as `1.0-SNAPSHOT` name "the newest development build". Each deploy stores a new uniquely named file; only the mapping from the snapshot name to the newest file moves. 2. **Aliases** such as an OCI tag `latest` or an npm dist-tag `latest` point at a version or a digest and are re-pointed on purpose. The rule is that these movable names are never used where a fixed identity is needed, and that release versions never behave like them. ## What to do when a release is broken 1. Stop the bleeding: tell consumers not to take the broken version. 2. Publish the fix as a **new version** (2.4.2), never as a rebuilt 2.4.1. 3. Mark the broken version as unsafe using whatever its ecosystem offers (deprecation, yanking or unlisting), so that installs that already pin it keep working while new ones are steered away. Overwriting is never on that list. The broken bytes are already in caches and lockfiles under that name, so an overwrite would reach some machines and not others, which is worse than the bug it fixes.

  • Why is an OCI registry tag not protected the way a package version is?
    In the OCI distribution spec a tag is a human-readable pointer to a manifest, and pushing a manifest to an existing tag moves the pointer. Harbor's own docs say users can re-push the same tag by default. The fixed identity is the manifest digest. Freezing a tag is an extra registry setting, such as a Harbor tag immutability rule, not a property of tags.
  • Does a checksum file next to the artifact prove that a release was never overwritten?
    No. A checksum stored beside the file is uploaded together with it, so a redeploy brings a matching new checksum. Maven Resolver's documentation says such checksums only provide integrity verification, not trust. Proof needs a hash recorded somewhere else earlier: a lockfile entry, a build log or a deployment record.

  • Overwriting a release is fine when the fix is small and urgent.
  • Unpublishing an npm version frees its number to be published again.
  • Clients always re-download a release, so an overwrite reaches everyone at once.
  • Every registry rejects a duplicate version by default, so no setting is needed.
  • A tag on an OCI registry is as fixed as a released package version.
open as a page

In package and container registries, how does an immutable version differ from a mutable name such as an OCI tag or an npm dist-tag?

level: middleimportance: must knowfreq 60%

basics

~20 s

A version or digest names fixed content and never changes; an OCI tag or npm dist-tag is a pointer the registry lets you re-aim. Use the movable names for discovery and record versions or digests for builds and deploys.

open as a page

In Harbor, how do tag immutability rules freeze release tags while letting moving tags such as latest keep changing?

level: middleimportance: should knowfreq 40%

basics

~20 s

Harbor tag immutability rules are project-level patterns over repositories and tags. A matching tag can no longer be re-pushed, re-tagged, overwritten by replication or deleted, so excluding moving tags such as latest keeps them mutable.

open as a page

After an internal library's version 2.4.1 was re-published with different contents and two services built different code from it, how do you prove it and prevent a repeat?

level: seniorimportance: should knowfreq 45%

basics

~20 s

Compare the hashes each service recorded at build time with what the repository serves now, and find the second upload in its history. Then make release repositories refuse redeploys and ship the fix as a new version.

open as a page

For an organisation's repositories and registries, which version names would you freeze, which may move, and how would you handle a bad release?

level: principalimportance: should knowfreq 30%

basics

~20 s

Freeze every release version and version-shaped tag on every server, allow only named aliases and snapshots to move, and fix bad releases with new versions. Rare takedowns delete with approval and never reuse the number.

open as a page