Releases · XB Field Notes

Image tags can move while existing containers keep their image

Tue, 24 Aug 2027 00:00:00 +0000

An image tag is a readable name associated with an image reference. Unless a registry policy prevents reassignment, the same tag can later identify another artifact. Tags such as v1.4 and latest differ in naming convention, not in an inherent guarantee of immutability. Reproducing a deployment requires recording the artifact actually selected, together with the platform and runtime configuration that determined its behavior.

When it breaks

The word latest does not ask a registry to find its newest image or highest semantic version. It is the conventional default tag when a reference omits one. Publishing or tagging another version does not automatically move latest; someone or some automation must update that specific reference. Treating every push as an implicit latest update gives an incorrect picture of release behavior.

A tag’s local resolution can also differ from its current registry resolution. Pull policy, local image availability, and orchestration behavior determine when the registry is consulted. Two machines running a readable tag can therefore use different artifacts. Recording only the command text leaves uncertainty about what each machine actually fetched and which cached reference it retained.

Moving a tag does not rewrite the image selected by an already-created container. Restarting that container retains its configured image and writable state rather than recreating it from the tag’s new target. An update procedure that retags an image and merely restarts existing containers can therefore appear successful while continuing to run the old application.

Check it quickly

Run this Python script with a Docker builder and the pinned base available. The recorded environment used Docker 29.3.1 on Linux arm64. All tags are unique local names; nothing is pushed to a registry. Containers use no network, and cleanup removes only the experiment’s container and tags:

from pathlib import Path
from tempfile import TemporaryDirectory
import json,subprocess,uuid

BASE='python@sha256:528257d48c1da0dcecc2e725d1ae34498d60c965f1241e39cd6a85a8859bdf84'
def docker(*args,check=True):
 result=subprocess.run(['docker',*args],capture_output=True,text=True,timeout=120)
 if check:assert result.returncode==0,result.stderr
 return result
def inspect(name,kind='image'):return json.loads(docker(kind,'inspect',name).stdout)[0]

name='xbcatm-tags-'+uuid.uuid4().hex[:10];tags=[name+':one',name+':two',name+':release',name+':latest'];container=name+'-old'
try:
 with TemporaryDirectory(prefix=name+'-') as directory:
 root=Path(directory)
 (root/'Dockerfile').write_text(f'FROM {BASE}\nCOPY version.txt /version.txt\nCMD ["cat", "/version.txt"]\n')
 for tag,version in zip(tags,['one','two']):
 (root/'version.txt').write_text(version+'\n');docker('build','--network','none','-t',tag,str(root))
 one=inspect(tags[0])['Id'];two=inspect(tags[1])['Id'];assert one!=two
 docker('image','tag',tags[0],tags[2]);docker('image','tag',tags[0],name)
 assert inspect(tags[2])['Id']==inspect(tags[3])['Id']==one
 docker('create','--name',container,'--network','none',tags[2])
 docker('image','tag',tags[1],tags[2])
 assert inspect(tags[2])['Id']==two and inspect(tags[3])['Id']==one
 assert inspect(container,'container')['Image']==one
 assert docker('start','--attach',container).stdout.strip()=='one'
 assert docker('run','--rm','--network','none',tags[2]).stdout.strip()=='two'
 assert docker('run','--rm','--network','none',tags[3]).stdout.strip()=='one'
 print('moving release changes newly created containers; the existing container still runs its original image')
 print('omitting a tag selected latest, but updating release did not update latest')
 docker('image','rm',tags[2]);assert inspect(tags[1])['Id']==two
 print('removing one tag leaves another reference to the same image intact; all operations stayed local')
finally:
 docker('rm','-f',container,check=False);docker('image','rm',*tags,check=False)

The script builds two images whose /version.txt contents are one and two. Their image identities differ. It points a release tag at the first image and tags that same image using a repository name with no explicit tag. Inspection confirms that the omitted tag became latest, and both references initially select the first image.

Before moving release, the script creates a container from it without starting the container. It then moves release to the second image. The release tag now identifies the second artifact, while latest still identifies the first. This isolates tag reassignment from the independent default-tag convention and demonstrates that related names do not automatically move together.

Starting the existing container prints one. Creating a new container from release prints two, while creating one from latest prints one. The container inspection also retains the original selected image identity. These assertions compare actual execution results, so the distinction does not depend solely on interpreting a table of tag names.

Removing the release tag leaves the second image available through its two tag. A tag is a reference, and removing one reference does not necessarily delete shared content or every other name. Image reclamation depends on remaining references and the engine’s storage rules; this experiment does not prune caches or measure physical space recovery.

The fixture compares identities returned by the current engine without assuming that every inspect Id universally means an OCI configuration digest. Modern image stores can expose different object levels. Registry indexes, platform manifests, image configurations, and layer blobs each have their own digests, so the object type and reference context must accompany an identity claim.

Promote the artifact that was tested

For registry deployments, record a repository-qualified digest reference from the publication workflow. A digest can identify an image index containing multiple platform-specific manifests; selecting the intended platform still matters. Retain the corresponding artifact and required blobs so a later rollback can actually retrieve them. A recorded hash cannot recover content that is no longer available.

Use tags as human navigation when useful, and enforce registry immutability rules if the release process promises that version tags never move. Verify the policy rather than inferring it from a version-shaped name. Digest pinning also does not prove who built an artifact or whether it is safe; provenance and behavioral validation answer those questions.

After deployment, compare the running workload’s selected artifact and expected behavior with the release record. An updated tag, a successful pull, and a running container are separate observations. The release is established by connecting them to the exact artifact that passed validation.

Sources

Docker image tag, local tag creation and the default latest tag, checked 2026-09-12.
Docker image pull, pulling repository artifacts by tag or digest, checked 2026-09-12.
OCI image index 1.1.1, an index referencing platform-specific image manifests, checked 2026-09-12.
OCI image manifest 1.1.1, manifest references to configuration and layer objects, checked 2026-09-12.

Promote a verified artifact through environments

Wed, 17 Feb 2027 00:00:00 +0000

A staging test establishes facts about the artifact and environment that actually ran. Building again before production creates another output whose identity must be checked or whose behavior must be revalidated. Promotion carries an already verified artifact to the next environment and records that decision. It removes one source of uncertainty, but it does not make staging and production equivalent or eliminate the need to verify the resulting deployment.

Name the unit that moves

Use an immutable package identifier or content digest to identify the build. A moving tag, branch name, or source commit alone does not uniquely establish the deployed bytes. Toolchains, dependency resolution, embedded settings, or packaging can change between builds of the same source. A reproducible rebuild might yield identical bytes; compare the result before treating it as the previously tested artifact.

Keep the build stage separate from the release stage. A release combines a particular artifact with the configuration required for a deployment. Runtime then executes that combination against actual dependencies and data. Record the artifact identity and a suitable configuration revision, without exposing secrets. If frontend settings are compiled into JavaScript during packaging, changing them creates different bytes and therefore a different artifact requiring validation.

When it breaks

A pipeline can say it promotes a release while a deployment script quietly recompiles it. Another pipeline can download the correct archive and overwrite a configuration file inside it. Both change the tested input. Decide which settings belong outside the immutable payload and make the deployment read them through the application’s existing configuration interface. Do not assume a checksum checked before a later mutation still describes the running files.

The same artifact can behave differently with a changed database schema, feature flag, dependency version, permission, resource limit, or network path. Promotion establishes continuity of bytes, not continuity of the entire execution context. Validate important production behavior after deployment and compare the relevant environment differences when staging results do not reproduce.

Rollback also has prerequisites. An older executable may not understand newly written records or a completed destructive schema migration. Returning a pointer to an earlier artifact cannot undo those external effects. Keep rollback instructions tied to data compatibility, configuration, and dependency state. When reversal is unavailable, plan the necessary forward repair rather than promising that selecting the old image always restores service.

Check it quickly

Save this as promote.py and run python3 promote.py. The script uses Python’s standard library, temporary directories, and HTTP servers bound only to loopback. It writes one tiny application artifact, records its digest, and copies it to two local environments. The label production-simulation names a temporary directory; no external deployment occurs.

from hashlib import sha256
from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
from pathlib import Path
from tempfile import TemporaryDirectory
from threading import Thread
from urllib.request import ProxyHandler, build_opener
import json
import runpy
import shutil

source = 'def render(config):\n return {"build": "local-build-41", "tier": config["tier"]}\n'
digest = sha256(source.encode()).hexdigest()


def verify(path):
 if sha256(path.read_bytes()).hexdigest() != digest:
 raise ValueError('artifact changed')


def handler(path, config):
 verify(path)
 render = runpy.run_path(str(path))['render']

 class Handler(BaseHTTPRequestHandler):
 def do_GET(self):
 data = path.read_bytes() if self.path == '/artifact' else json.dumps(render(config)).encode()
 self.send_response(200)
 self.send_header('Content-Length', str(len(data)))
 self.end_headers()
 self.wfile.write(data)

 def log_message(self, *args):
 pass

 return Handler


with TemporaryDirectory() as directory:
 root = Path(directory)
 artifact = root / 'build.py'
 artifact.write_text(source)
 opener = build_opener(ProxyHandler({}))
 observed = []
 for tier in ('staging-local', 'production-simulation'):
 destination = root / tier
 destination.mkdir()
 deployed = destination / 'app.py'
 shutil.copyfile(artifact, deployed)
 config = {'tier': tier}
 server = ThreadingHTTPServer(('127.0.0.1', 0), handler(deployed, config))
 thread = Thread(target=server.serve_forever)
 thread.start()
 try:
 origin = f'http://127.0.0.1:{server.server_port}'
 with opener.open(origin + '/artifact', timeout=5) as response:
 received_digest = sha256(response.read()).hexdigest()
 with opener.open(origin + '/', timeout=5) as response:
 rendered = json.load(response)
 assert received_digest == digest
 assert rendered == {'build': 'local-build-41', 'tier': tier}
 observed.append({'artifact_sha256': received_digest, 'response': rendered,
 'config_sha256': sha256(json.dumps(config, sort_keys=True).encode()).hexdigest()})
 finally:
 server.shutdown()
 thread.join()
 server.server_close()
 deployed.write_text(source + '# rebuilt\n')
 try:
 verify(deployed)
 except ValueError:
 changed_rejected = True
 else:
 changed_rejected = False
 assert changed_rejected
 print(json.dumps({'environments': observed, 'changed_copy_rejected': changed_rejected}))

Before starting each server, the script verifies the copied file against the original digest and loads its application function. Fetching /artifact returns the deployed bytes; fetching / executes that function with the environment’s separate configuration. Both HTTP downloads have the same artifact hash, and both responses name local-build-41.

The response’s tier differs between environments, and the recorded configuration hashes differ as well. Those configurations contain only harmless labels. The result demonstrates how identical application bytes can intentionally produce different behavior. After the servers stop, a changed copy is rejected by the same digest check, so a silent rebuild cannot pass this particular identity gate.

The fixture does not model a registry, authentication, database migration, production traffic, or rollback. It establishes the local transfer, validation, and configuration boundary using actual file copies and HTTP responses. It cannot establish that a real deployment system enforces the same rules.

Verify the release that actually runs

Attach the promotion decision to the artifact and configuration revision, then check the deployed process or served files instead of relying solely on a successful upload. Retain the approved artifact for the required recovery window. If a later step generates a different package, give that output a new identity and its own relevant validation. A useful promotion record answers which bytes moved, what configuration accompanied them, and what behavior was observed after the move.

Sources

The Twelve-Factor App: build, release, run, separate build artifacts from releases and execution, checked 2026-09-13.
The Twelve-Factor App: config, configuration that varies between deploys, checked 2026-09-13.

Semantic versioning makes compatibility explicit

Sat, 13 Feb 2027 00:00:00 +0000

A dependency version is useful when its publisher and consumers agree on the public contract. Semantic Versioning gives changes a vocabulary: from version 1.0.0 onward, incompatible public API changes require a major increment, compatible additions require a minor increment, and compatible fixes require a patch increment. The number summarizes a claim about a release. It does not inspect its implementation or guarantee that an upgrade will work in your application.

Declare what compatibility covers

A public API can include exported functions, documented command options, configuration formats, response fields, and specified error behavior. Write that boundary clearly enough to decide whether a change violates it. An internal refactor that preserves the contract differs from removing a documented option. A correction to behavior that contradicted the contract can be a compatible bug fix even though somebody observed the old behavior. Explain that change in release notes and test affected consumers.

SemVer requires a minor increment when public functionality is marked deprecated. Removal later requires the appropriate incompatible release. Once a version has been released, its contents must not change; publish another version for a correction. Replacing the bytes behind the same version defeats traceability and can produce different installations from identical dependency declarations.

Major version zero signals initial development, with an API that should not be considered stable. A publisher may describe additional conventions for that phase, but do not assume every zero-major update is compatible. Prereleases have lower precedence than the corresponding normal release. Build metadata after + is ignored when determining precedence, so equal precedence does not imply identical packages or hashes.

When it breaks

A dishonest minor release can break a documented contract despite satisfying a consumer’s version range. A correctly labeled release can also expose an application that relied on undocumented internals. Read the changelog, run meaningful integration checks, and retain a lockfile when the build needs repeatable dependency selection. A lockfile records selected versions; it does not certify their behavior or authenticity.

Package manager ranges are another boundary. SemVer defines versions and precedence, while tools define how constraints select candidates. In node-semver, a caret generally permits changes to the right of the leftmost nonzero component. Consequently, ^0.2.3 excludes 0.3.0, and ^0.0.3 excludes 0.0.4. A tilde with all three components permits patch changes within that minor line.

Prerelease selection has additional rules. A broad stable range does not automatically accept a newer beta. Explicitly allowing a prerelease tuple can admit subsequent prereleases for that tuple. Verify the resolver’s actual behavior instead of applying ordinary string sorting or treating every numerically larger version as an eligible update.

Check it quickly

Save this as semver.py and run python3 semver.py with Node and npm available. Internet access to the public npm registry is required. The script installs semver@7.7.2 into a temporary directory with isolated configuration and cache, disables package scripts, and runs the library’s actual comparison functions. It does not edit the current project’s dependencies.

from pathlib import Path
from tempfile import TemporaryDirectory
import json
import os
import subprocess

with TemporaryDirectory() as directory:
 root = Path(directory)
 user_config = root / 'user.npmrc'
 global_config = root / 'global.npmrc'
 user_config.write_text('')
 global_config.write_text('')
 env = {'PATH': os.environ['PATH'], 'LC_ALL': 'C',
 'NPM_CONFIG_USERCONFIG': str(user_config),
 'NPM_CONFIG_GLOBALCONFIG': str(global_config),
 'NPM_CONFIG_CACHE': str(root / 'cache')}
 subprocess.run(['npm', 'install', '--ignore-scripts', '--no-audit', '--no-fund',
 '--package-lock=false', '--registry=https://registry.npmjs.org',
 'semver@7.7.2'], cwd=root, env=env, check=True, capture_output=True)
 script = r'''
const s = require('semver');
const assert = require('node:assert/strict');
const cases = [
 ['1.9.0', '^1.2.3', true], ['2.0.0', '^1.2.3', false],
 ['1.2.9', '~1.2.3', true], ['1.3.0', '~1.2.3', false],
 ['0.2.9', '^0.2.3', true], ['0.3.0', '^0.2.3', false],
 ['0.0.4', '^0.0.3', false], ['1.3.0-beta.1', '^1.2.3', false],
 ['1.3.0-beta.2', '^1.3.0-beta.1', true]
].map(([version, range, expected]) => {
 const accepted = s.satisfies(version, range);
 assert.equal(accepted, expected);
 return {version, range, accepted};
});
assert.equal(s.compare('1.2.3+build.1', '1.2.3+build.2'), 0);
assert.equal(s.lt('1.3.0-beta.2', '1.3.0'), true);
assert.equal(s.valid('1.02.3'), null);
console.log(JSON.stringify({library: require('semver/package.json').version, cases,
 metadata_precedence_equal: true, prerelease_before_release: true, leading_zero_rejected: true}));
'''
 result = subprocess.run(['node', '-e', script], cwd=root, env=env,
 capture_output=True, text=True, check=True)
 print(json.dumps(json.loads(result.stdout)))

The nine range cases must match their recorded expectations: caret accepts 1.9.0 under ^1.2.3 but rejects 2.0.0; tilde rejects the next minor; the zero-major cases remain narrower. The stable range rejects 1.3.0-beta.1, while the explicitly prerelease range accepts 1.3.0-beta.2.

The remaining assertions establish that two build metadata variants compare equally, a beta precedes its normal release, and a leading zero in 1.02.3 is invalid. These results verify parsing and selection, not the compatibility of any real library update. Pair a proposed version bump with evidence about the changed API and the consumers affected. The version communicates that judgment; release notes and tests make the judgment assessable.

Sources

Semantic Versioning 2.0.0, public API promises, precedence, and initial development, checked 2026-09-13.
npm: node-semver, caret, tilde, and prerelease range behavior, checked 2026-09-13.

Releases · XB Field Notes

Image tags can move while existing containers keep their image

When it breaks

Check it quickly

Promote the artifact that was tested

Sources

Promote a verified artifact through environments

Name the unit that moves

When it breaks

Check it quickly

Verify the release that actually runs

Further reading

Sources

Semantic versioning makes compatibility explicit

Declare what compatibility covers

When it breaks

Check it quickly

Further reading

Sources