Release Manifest

A team releases a backend container and three signed mobile bundles every two weeks. Promotion today means moving a tag, and the tag resolves independently in each environment. The claim "production runs what was tested" is therefore false for three of the four artefacts, and nobody will notice until a region behaves differently from its neighbour.

A release manifest fixes the referent. It is a small document listing every artefact by content digest, together with the commit and build that produced each, the configuration values, the feature flag defaults and the migration set. Promotion is signing that document for the next environment; deployment is resolving it.

Why it matters

A digest is content; a tag is a pointer. Two deployments naming service:1.8.2 can be different images, and that single fact accounts for a large share of "it works in one region and not the other" investigations.

The second reason is atomicity. Four artefacts tested together should be promoted together or not at all. Independent promotion permits a state where the backend is promoted and one mobile bundle is a day old, with no record that the combination was never verified.

The third is the audit question. "What was in the release on 12 March?" should be a file, signed, in version control, not an archaeology exercise across four pipelines.

And the part most often missed: a promotion pinning only the image is a partial promotion. Configuration values, flag defaults and the migration set are part of what makes a release, and if they are resolved fresh at deploy time the promoted thing is not the thing that ships.

Implementation patterns

• Content digests only, never tags, for every artefact in the manifest.
• Include the non-artefact inputs: chart or manifest values, flag defaults, the ordered migration set, and the identity of the base images used.
• Sign it at the point of promotion, by the system that made the promotion decision, so the signature records who promoted and when.
• Resolve, do not interpret. The deployer reads the manifest and applies exactly what it names; it must have no mechanism for picking a newer anything.
• Record where each manifest is deployed. The manifest answers "what is in this release"; a separate append-only ledger answers "what is running now", which is the question asked during an incident.
• Keep it small and human-readable. Someone will read it under pressure.

Industry example

The pattern is the backbone of GitOps-style delivery, where the desired state of an environment is a versioned, reviewable document and the reconciler's job is to make reality match it. It is also exactly what container image digests exist for: the OCI image specification makes the digest the canonical identifier and the tag a mutable convenience, and every registry's documentation warns against relying on tags for reproducibility.

The failure it prevents is documented from the other direction. CrowdStrike's July 2024 incident, in which a content update rather than a sensor release crashed Windows hosts worldwide — Microsoft estimated about 8.5 million devices — is the standing illustration that anything shipped to production is part of the release whether or not the release process names it. A manifest that lists only the code artefacts leaves the same gap.

Failure scenarios

• A tag moved between environments, so two regions run different code under one version number.
• Configuration resolved at deploy time, so the promoted image meets values it was never tested with.
• A migration applied out of order because the set was not pinned, and the schema is now ahead of the code in one environment.
• A manifest treated as advisory by a deployer that falls back to "latest" when a digest is missing, which silently defeats the whole mechanism.
• A manifest with no deployment record, so during an incident the team knows the release contents and not where they are running.
• Digest drift from rebuilds, where a well-meaning pipeline rebuilds an artefact for an environment and the manifest no longer describes what runs.

Trade-offs

Pinning everything buys reproducibility and an audit answer, and costs flexibility at deploy time: nothing can be changed without producing a new manifest, including an urgent configuration fix. That is usually the point, and it needs a defined fast path for genuine emergencies or people will edit around it.

It also costs a build step, a verification step on every deployment and a signing key to manage. For a single artefact going to a single environment, that is ceremony; the pattern earns its place at two or more artefacts that must move together, or at the first audit question nobody can answer from memory.

When not to use it

One artefact, one environment, one team. Promote the digest directly and keep the pipeline simple.

Also when the artefacts genuinely release independently behind versioned contracts — a platform library and a service that consumes it, each with its own compatibility guarantees. Linking them in a manifest then forces coupling that the versioning was designed to remove, and the result is releases waiting on each other for no reason.

Interview question

Q: Your team promotes by moving a git tag. An auditor asks you to prove that the code running in production is the code that passed security review three weeks ago. Walk me through what you can prove today and what you would change.

What a strong answer covers: admitting what a tag proves, which is intent rather than content, and that each environment resolved it independently · the gap beyond the image: configuration, flag defaults and migrations resolved at deploy time · introducing a signed manifest of digests as the unit of promotion, with resolution and no fallback in the deployer · the second artefact needed for the auditor's actual question, which is a record of which manifest is running where and since when · the cost, which is reduced deploy-time flexibility and a required emergency path · and the honest scope limit, that for one artefact and one environment none of this is worth building.

Quick check

Quiz: Why is promoting by tag insufficient even when the registry currently shows one digest for that tag? — Because a tag is mutable and resolved late, so a later deployment can resolve it differently, and it records intent rather than the content that actually ran.

Flashcard: What must a release manifest include beyond artefact digests? — The configuration values, feature-flag defaults and the ordered migration set, because anything resolved fresh at deploy time was never part of what was tested.