Replacing the Container Image as Your Unit of Promotion With a Declarative Environment Manifest

A pinned, human-readable declarative environment manifest should be the unit of promotion across development, staging, and production. It specifies the intended environment. Promoting that contract makes dependency changes reviewable, rollback a version-control operation, and supply-chain provenance a property of every stage of the software development lifecycle.

How the container image became the unit of promotion without anyone deciding it should be

A portable, self-contained runtime artifact could move from a developer’s machine to CI and production with less configuration friction. That was a big step up from putting an environment together at each destination. Teams adopted the artifact that made deployment more predictable, and pipelines grew around building, scanning, tagging, and pushing it. Promotion inherited its boundary from packaging rather than from an explicit decision about what each stage should validate.

That boundary became the contract between teams and environments. Yet an image records the runtime state produced when a build ran, while the decisions defining the intended environment, including package versions and configuration choices, remained in the build scripts upstream. Downstream reviewers received the compiled result. The image could therefore move unchanged even though the promotion contract did not cover how the declared inputs matched what was deployed.

This distinction separates two jobs that became coupled through practice. Packaging supplies something the runtime can execute, while promotion establishes what has been approved to advance. An image answers what a build produced. A declarative environment manifest answers what the environment is intended to contain.

What the build-scan-tag-push cycle actually does to drift, opacity, and supply chain risk

When build-scan-tag-push runs for each environment on its own, teams build again each time they promote. A network dependency, floating version reference, or condition resolved differently can make staging and production diverge despite sharing the same source. Each execution introduces another opportunity for change. The governing principle is that production should receive the artifact already validated below it, byte-for-byte where possible. Rebuilding from the same blueprint does not provide that guarantee.

Even where teams advance an unchanged image, review remains indirect. A tag identifies an artifact but does not explain its dependency graph or make changes between versions self-evident. Reviewers need information outside the tag to understand what they are approving. A similar problem comes up when someone patches a live workload without updating its deployment manifest. The declared state then stops describing the real system, weakening troubleshooting, auditability, and rollback even though the file still looks authoritative.

Supply-chain exposure also comes from this split between what was declared and what was built. Base layers, installed packages, and transitive dependencies resolve during the build, and downstream stages treat what ends up inside as a single unit. A tag cannot reveal a vulnerable dependency. A separate scan or an SBOM generated after the build must reconstruct what ended up inside. That retrospective account can describe the result, but it does not establish the intended dependency graph before construction or close the exposure window preceding the account.

Why a declarative environment manifest is a structurally different kind of artifact

A declarative environment manifest makes desired state the artifact under review. It specifies dependencies and configuration rather than asking reviewers to infer them from a build’s output. Human-readable declarations let engineers inspect changes, while machine-verifiable references let pipelines check the specification without first executing a build. The manifest becomes the operational contract between developers, platform teams, and the runtime.

That contract requires more than declarative syntax. Dependencies must be pinned to cryptographic digests at authoring time rather than left to floating resolution during execution. Otherwise, the file preserves instructions while allowing their meaning to change. When the environment is fully specified, each run uses the same declared dependency graph. Review rigor is essential because an incorrect selector or missing environment variable can still produce a deployment that looks valid but fails at startup or behaves incorrectly under load.

Version control also gives environment changes an atomic rollback boundary. Reverting to a previous manifest version restores the prior environment specification without rebuilding it or reconstructing a sequence of manual edits. This rollback is limited to the declared environment specification. The boundary is explicit and reviewable. Because the inputs are fully specified, their input-derived hash can serve as a stable environment identifier, linking a deployment to the exact dependency graph that was declared.

How manifest-driven promotion makes supply chain provenance a first-class property of every stage

When dependencies are pinned and visible, teams can account for the supply chain before deployment. For a fully specified environment, an SBOM can derive directly from the declared dependency graph rather than depend solely on a retrospective examination of a binary artifact. Intent becomes available before the environment advances. Attaching the input-derived hash to each deployment then links that declaration to its destination. Provenance becomes part of the promotion contract rather than a separate document associated with a tag.

Regulatory and customer expectations make that linkage increasingly useful. US Executive Order 14028 established pressure for SBOMs in federal software procurement, although OMB M-26-05 made those requirements discretionary rather than mandatory across the board in January 2026. The EU Cyber Resilience Act mandates SBOMs for products with digital elements sold in the EU. Customers are also beginning to request provenance attestations. These demands favor clear dependency records, though the same requirement does not apply everywhere software is bought.

When a CVE affects a declared dependency, deployments can be queried through their input-derived hashes, provided the manifest remains the enforced contract for what runs. Hash-level blocking or patching then operates on a traceable environment identity. The same principle applies to rendered Kubernetes manifests. Rendering once, storing the result durably, and syncing plain YAML preserves the reviewed artifact, whereas running Helm or Kustomize at sync time adds a late transformation between approval and application. This repeats at a different layer the mistake of treating shared build instructions as an unchanged deployment artifact, here by relying on a shared template.

How do CI/CD pipelines promote a manifest instead of an image?

The pipeline validates the manifest in a lower environment and advances that same artifact with explicit environment-specific inputs. One body of code has one input file per environment. Instance sizes, endpoints, and feature flags may vary, but deployment logic does not. The same deploy job serves each destination. This structure makes the manifest the invariant and the input files the controlled source of variation, rather than maintaining separate implementations that gradually diverge.

Review gates consequently change what they expose to approvers. Instead of approving a tag, a reviewer examines the manifest diff and the relevant environment inputs. Expected differences remain visible rather than being confused with accidental divergence. An unexplained production-bound change absent from staging points to divergent inputs, drift, or a race. Rollback follows the same path in reverse by advancing the previous known-good manifest version, without an environment rebuild or manual reconfiguration.

CI-based rendering, sourceHydrator, Kargo, and OCI artifacts offer approaches with different trade-offs between operational complexity and automation depth. Their shared requirement is durable rendered output. However, artifact consistency cannot compensate for unrepresentative staging. Staging must be production-shaped, with fewer nodes or smaller instances where appropriate but the same database engine, network topology, and ingress path. Otherwise, a successful validation tests a different kind of environment from the one that will receive the promotion.

How developer onboarding and day-to-day workflow change when the manifest is the shared contract

README-driven onboarding asks each developer to execute a procedure. That procedure has network dependencies and runs at a particular time, so identical instructions can produce different environments on different machines. A versioned, executable environment specification instead makes onboarding a process of pulling the manifest and activating its declared environment. On supported architectures, the developer receives the same pinned dependency graph rather than an approximation assembled from setup prose.

This takes over environment setup from README paragraphs, ad-hoc install scripts, and wiki caveats, while documentation still has other jobs. The specification itself defines the dependencies required to work on the project. As a result, setup knowledge no longer needs a parallel procedural form that can fall out of step with the environment. The contract is available in version control. A new contributor and an existing maintainer can refer to the same declaration when diagnosing an environment mismatch.

Day-to-day work on dependencies goes through the same review as application code. A developer edits the manifest, submits the change for review, and the approved version proceeds through staging and production. During local iteration, returning to an earlier environment generation uses the same version-revert mechanism as production rollback.

Why AI agents require the same environment rigor as human developers — and what happens when they don't get it

An AI agent’s execution context is a development environment too. If that context is underspecified, the agent can produce code that works there but fails in production because the dependencies or available services differ. Running generated code directly on sensitive infrastructure without isolation and environment controls also adds risks of drift and problems with provenance. The speed and volume of agent-produced changes compound those risks, reinforcing the need for a runtime contract.

A declarative manifest gives agent execution an explicit reference state. The runtime is pinned, dependencies are declared, and outputs can be validated against a known environment. Human and agent work share the same boundary. This removes an underspecified environment as the basis for claiming that the code was validated. Isolation remains necessary because reproducibility and permission to affect infrastructure are different properties.

When the manifest also declares available tools and services, it defines an access-control surface. What an agent may call, read, or modify becomes part of the environment contract. That declaration must be enforced by the environment controls. With tool calls recorded as structured events against the declared environment, auditing can recover the action, its execution context, and the input-derived hash at the time. The environment identity supplies the link between permitted access and the context in which a particular action occurred.

What platform engineers actually change when they adopt the manifest as the unit of promotion

Platform ownership shifts toward publishing and maintaining versioned environment manifests. A curated base manifest becomes the foundation that teams extend for their workloads, rather than each team maintaining an independent lineage of build instructions. Composition provides a shared update path. Branches and pull requests can create environments that inherit configuration from their parent, while infrastructure changes enter the same review process as application changes. The platform’s responsibility becomes maintaining those contracts and the promotion mechanisms that enforce them.

This is an operational form of Platform as Code. Declarative platform definitions support self-service provisioning, ephemeral environments on demand, and parameterized promotion pipelines. Existing container workflows need not disappear. Environments defined this way can still emit OCI images where those workflows require them, with the manifest remaining the source of truth and the image serving as one possible output.

Today, decisions about the environment are spread across build scripts, setup caveats, and per-team conventions, each with its own paths for review and enforcement. A manifest with rules for review and enforcement puts those decisions under version control. Because each environment traces back to an input-derived hash, the platform can make SBOM generation, CVE blocking, and provenance attestation properties of promotion itself. Governance then acts on the same declared contract that developers review, staging validates, and production receives.