Promote One Verified Digest Through Review, Not a Command

Mateo's releases still depend on laptop commands. His team knows the approved commit but can't show which image reached each environment. When staging and production diverge, someone copies the staging files and applies them directly to production.

The application works. But Git no longer describes production, so the next engineer can't explain the difference.

Chapter 7 starts from that composite scenario, and its answer is narrow on purpose: promote one verified image digest through a reviewed Git change.

Promotion Moves Identity, Not Files

A container tag is a convenient pointer that can move. A digest identifies specific image content.

So promotion shouldn't mean rebuilding an image for production, and it shouldn't mean copying the staging overlay over production. Copying can carry environment-specific labels, patches, or fault settings across the boundary. Promotion means changing production to the digest that was reviewed for staging, and nothing else.

The book's recommendation is short: build once, verify once, and promote the same digest.

What "Verified" Has to Mean

A well-formed sha256: string isn't enough. In Chapter 7, a verified digest is one accompanied by accepted upstream evidence naming five things:

• the image repository and full digest;
• the source revision and build run;
• the required test and policy results;
• the approving role;
• the evidence time or freshness rule.

The reviewer must trace the proposed digest to those fields. A digest without that chain is only a candidate digest, and it must not be promoted.

One Line, Three Checks

Here's the chapter's worked example, with illustrative, abbreviated digests. Staging has accepted reference-app@sha256:7a9c...e214. Production still declares the previously approved reference-app@sha256:19bf...82d0. The promotion proposal changes only the production digest to sha256:7a9c...e214.

The reviewer checks three things:

1. the proposed value equals the accepted staging digest;
2. the rendered production image contains that value;
3. the diff carries no staging-only patch or unrelated policy change.

Rendering is local. Kustomize supports setting an image by digest, and kubectl kustomize renders the result:

git diff -- deployment/gitops/
kubectl kustomize deployment/gitops/overlays/production \
  > /tmp/reference-production-promoted.yaml
grep -F "@${STAGING_DIGEST}" /tmp/reference-production-promoted.yaml

Compare that with changing production to reference-app:stable. The registry could later move that tag without any Git diff, so identity would no longer be reviewable.

Review Is Not the Same as Sync

The chapter uses Argo CD to split the two environments by policy. The staging Application declares automated synchronization, pruning, and self-healing, because staging is the proving environment. The production Application omits automated synchronization. A reviewed commit and an approved digest are necessary, but an authorized human still triggers and checks the production sync.

The book is careful about what that split does and doesn't do. Manual sync isn't approval; repository controls and Argo CD access controls must separately enforce who may approve and who may trigger production changes. The split isn't universal either: some teams automate production after stronger tests and recovery evidence, and regulated environments may need more separation.

Synced Is Not Healthy

Synced means the live state matches the desired state as the controller understands it. It doesn't mean the service is reachable or behaving correctly. Healthy is a separate resource assessment, and application traffic bypasses the controller entirely.

Digest equality has the same kind of limit. It proves the production artifact has the same identity as the staging artifact. It doesn't prove the image is safe, that the controller reconciled it, or that the workload became healthy.

Test Intent, Not Just Syntax

The chapter's deliberate failure is a one-line mistake that a parser would happily accept: the production Application points at the staging overlay. On a temporary copy, you swap the production source path for the staging one and confirm that a route check rejects it.

The YAML is still valid, and a controller might reconcile it if project rules allowed the destination. That's the lesson: validation has to encode environment relationships, because a schema can't know that a production Application must not read the staging overlay.

Where the AI Assistant Fits

An AI assistant in this workflow reviews sanitized declarations and diffs as a critic, not an operator. It may summarize the diff, but it cannot attest that tests passed. Watch for the familiar shortcuts: equating Synced with health, treating manual sync as approval, or recommending mutable tags and wildcard permissions.

Read the Full Design

Chapter 7 is a design-only review. The companion supplies the declarations and local checks; live reconciliation is an optional route that needs authorization and its own evidence. The chapter's platform log entry says so plainly: it does not prove approval enforcement, admission, reconciliation, runtime health, or cleanup on a live cluster.

The chapter walks through the AppProject's authority limits, drift handling, and negative tests in full. The declarations live under deployment/gitops/ in the companion repository at https://github.com/netbiz-ai/ai-native-devops-companion.