Last reviewed: 2026-08-05

Direct answer

A coding agent container image digest review should turn every tag-only deployment proposal into an explicit content identity before the change merges. Resolve the intended tag against the approved registry, record the returned digest, determine whether it identifies a multi-platform index or one platform-specific image, and replace the mutable reference with the reviewed digest. If your organization verifies image signatures, verify the pinned reference against the approved signer identity and issuer as a separate step.

Treat the coding agent as the author of a proposal, not the authority that approves the image. The agent may locate manifests, run read-only inspection commands, and prepare a focused patch. A reviewer or trusted CI control should confirm the registry, digest, platform coverage, verification result, and rollback reference. Never accept a digest merely because it is well formed or appears in prior output.

The safe result is a deployment definition whose image content cannot change without another source change. If resolution changes during review, signature verification fails, the required platform is missing, or the rendered deployment differs from the reviewed patch, stop the merge and preserve the previous known digest.

Who this is for

This workflow is for developers, platform engineers, security reviewers, and repository maintainers who review coding-agent edits to Kubernetes manifests, Helm values, Kustomize overlays, job definitions, or other container deployment configuration. It is especially useful when an agent upgrades a base image, changes an application release, replaces :latest, or edits several environment overlays at once.

You do not need to ban tags from release management. Tags remain useful as human-readable discovery labels. The control described here is narrower: the deployed identity should be the digest that a reviewer resolved and approved.

Key takeaways

  • A tag can move; a digest identifies specific image content.
  • Digest pinning and signature verification answer different questions. The digest fixes what will run, while verification checks whether the signed identity satisfies your trust policy.
  • Multi-platform images require an explicit decision between the index digest and a platform-specific child digest.
  • The agent should show how it obtained the digest and every manifest it changed.
  • Any failed or ambiguous check should produce a blocked change, not a silent fallback to a tag.
  • Keep the previous digest with the review evidence so rollback does not depend on resolving a mutable label later.

Sources checked

  • Docker’s Image digests documentation defines an image digest as a SHA-256 content identifier. It explains that tags can be reused or changed, whereas a digest is immutable, and it distinguishes a multi-platform manifest-list digest from the child digests for individual platforms.
  • Kubernetes Images documentation recommends avoiding :latest in production because it makes the running version and rollback harder to track. It documents digest-based image references as the way to select a specific image version.
  • Sigstore’s Verifying Signatures guide documents identity-based verification with Cosign. It also states that Cosign signature payloads include the container-image digest and that normal verification checks that digest against the image.

Together, these sources support the core contract: resolve an immutable content identity, choose the correct platform scope, and independently enforce the expected signing identity when signatures are part of policy.

Contract details to verify

A digest-pinning task needs more than an instruction to replace tags. Give the agent and reviewer a small, testable contract containing:

  • the exact image repository and registry namespace;
  • the approved release tag used for discovery;
  • every base manifest, overlay, chart value, generated file, and workload type in scope;
  • the operating systems and CPU architectures the deployment must support;
  • whether policy requires an index digest or a platform-specific digest;
  • the approved signer identity and issuer policy, if signature verification is required;
  • the previous deployed digest and the rollback owner; and
  • the commands and sanitized evidence that must accompany the pull request.

The final manifest should use digest syntax. This is an illustrative shape; the digest below is deliberately an example and must not be copied into a real deployment.

apiVersion: apps/v1
kind: Deployment
metadata:
  name: checkout
spec:
  template:
    spec:
      containers:
        - name: checkout
          image: registry.example.com/platform/checkout@sha256:0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef

Happy-path operator workflow

  1. Bound the change. Ask the agent to list every existing image reference and the file or generated layer that supplies it. Compare that inventory with the task brief. Unrelated resource, permission, network, or rollout edits should leave the patch or receive separate review.

  2. Resolve the approved tag. Run a read-only inspection against the trusted registry endpoint. Record the complete repository name, requested tag, returned digest, media type, and platform entries.

docker buildx imagetools inspect registry.example.com/platform/checkout:2.4.1

Do not let the agent infer a digest from an image name, copy one from another repository, or truncate it in the manifest. A shortened digest may be useful in prose, but the deployment reference and evidence record need the complete value returned for that repository.

  1. Choose the digest scope. For a heterogeneous cluster, an approved manifest-list or image-index digest can retain platform selection while fixing the overall image set. A policy that deploys one known platform may instead require that platform’s child digest. Record the choice as manifest_list or platform_image; do not leave reviewers to infer it from a long hash.

  2. Verify the signed identity when required. Populate the approved signer and issuer values from trusted policy, not from pull-request content, and verify the same digest that will appear in the deployment.

cosign verify --certificate-identity=$APPROVED_SIGNER_IDENTITY --certificate-oidc-issuer=$APPROVED_OIDC_ISSUER registry.example.com/platform/checkout@$APPROVED_DIGEST

Keep Cosign’s normal digest-claim validation enabled. A successful signature from an unexpected identity is not an approval; match both identity and issuer to the allowlist established for that image repository.

  1. Patch every effective reference. Update the source manifest and any overlay that can replace it. Check application containers, init containers, scheduled jobs, migration jobs, and environment-specific values. If the repository commits generated deployment output, regenerate it with the repository’s established toolchain and keep generator-only churn out of the patch.

  2. Validate the rendered deployment. Review the final image field after templates and overlays have been applied. Use the repository’s established validation path, then perform a server-side dry run or diff in an authorized test environment when available.

kubectl diff -f deploy/checkout.yaml
kubectl apply --dry-run=server -f deploy/checkout.yaml

The digest in the rendered workload must match the digest inspected and verified earlier. Check that the change did not alter replica counts, service accounts, volumes, probes, or other deployment fields outside the brief.

  1. Record the decision. Attach the sanitized evidence fields below, the focused manifest diff, and the previous digest. The reviewer can then approve a stable content identity rather than a tag that may resolve differently later.

The happy path ends only when the intended repository, full digest, digest scope, platforms, signature result, rendered manifest, and rollback digest agree.

Error-path operator workflow

Stop the change if a second inspection of the tag returns a different digest before approval. Record tag_moved_during_review, retain both observations, and ask the release owner to identify the intended build. Do not choose the newest value automatically.

Stop if Cosign cannot verify the signature, if the identity or issuer is outside policy, or if the verified claim does not match the deployment digest. Categorize the result without pasting unfiltered command output. The agent may investigate, but it should not weaken verification or replace the digest with a tag to make the check pass.

Stop if the selected index omits a required platform or if a child digest targets the wrong platform. Return the patch for correction before deployment testing. Also stop when the rendered output changes more than the reviewed source patch, because an overlay or generator may be overriding the apparent image reference.

If the registry is unavailable, leave the prior digest in place and mark the update unresolved. Registry failure is not evidence that the mutable tag is acceptable. When correction is needed, ask for a focused follow-up rather than mixing emergency edits into the original agent diff.

Sanitized evidence log

A compact record makes the review reproducible without collecting sensitive runtime data:

event: container_image_review
result: approved
repository: platform/checkout
change_id: pr-1842
deployment_path: deploy/checkout.yaml
image_repository: registry.example.com/platform/checkout
requested_tag: 2.4.1
resolved_digest: sha256:0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef
digest_scope: manifest_list
platforms_checked:
  - linux/amd64
  - linux/arm64
signature_check: verified
signer_identity: allowlisted-release-workflow
rendered_manifest_match: true
rollback_digest_recorded: true

On an error path, set result to blocked and add a short category such as tag_moved_during_review, signature_identity_mismatch, digest_claim_mismatch, required_platform_missing, or rendered_manifest_mismatch. Store command exit status and a concise diagnostic, not the complete process environment, registry authentication material, or unrelated client configuration.

Failure modes

Pinning the wrong repository’s digest. A digest-looking value is not enough. Bind the evidence to the full registry and repository name, then verify the exact reference used in the manifest.

Resolving a moving tag only once. A tag can change between task execution and approval. Recheck it at the review boundary and block if its value moved.

Confusing an index with a child image. Pinning one architecture’s child digest can break another platform. Conversely, recording only an index when policy requires per-platform verification leaves the contract incomplete.

Treating a digest as publisher proof. A digest identifies content; it does not by itself establish who produced or approved it. Where policy requires provenance, verify the signed identity and issuer for the digest.

Accepting any valid signer. Cryptographic success is not the same as policy success. Verification must match the repository’s allowlisted identity, not merely return a successful exit status.

Editing the base file while an overlay wins. The source diff can look correct while the rendered workload still uses a tag or another digest. Always inspect effective output.

Falling back silently. Replacing a failed digest reference with :latest or another tag restores mutability and hides the original failure. A failed check should remain visible and block the update.

Bundling unrelated deployment changes. Digest pinning becomes harder to review when replica, permission, storage, or networking changes share the patch. Split those concerns so the image decision remains auditable.

Losing the rollback identity. A release tag may no longer identify the prior image when rollback is needed. Record the previous full digest before approving the new one.

FAQ

Does a digest prove that an image is safe?

No. It proves which content the reference identifies and lets the runtime request that same content again. It does not, on its own, identify the publisher or express your organization’s approval. Signature verification and other release controls remain separate decisions.

Should tags disappear from the release process?

No. A meaningful tag can help an operator locate the proposed release and understand its human-facing version. Resolve that tag during review, but use the approved digest as the deployment identity. Record the tag-to-digest relationship as an observation made at review time, not as a permanent guarantee that the tag will never move.

Which digest should a multi-platform deployment use?

Choose deliberately. An index digest identifies the overall multi-platform image and refers to platform-specific children. A child digest identifies one platform image. Use the scope required by your deployment topology and verification policy, then record the supported platforms in the evidence.

Can the coding agent choose the digest automatically?

The agent can retrieve and propose it, but approval should come from a trusted reviewer or policy control. Require the agent to show the repository, inspection command, complete result, platform scope, and final diff. Never let the same unreviewed output define both the expected value and the evidence used to approve it.

What if the image has no signature?

Do not pretend digest pinning supplied provenance. Record signature verification as unavailable and apply the repository’s stated release policy. The digest can still make the content reference reproducible, but any requirement for an approved publisher remains unresolved until the proper evidence exists.

How should a pinned image be updated later?

Resolve and review the new release in a new focused change. Capture the old and new digests, repeat platform and signature checks, validate rendered output, and preserve the old digest for rollback. Pinning intentionally makes an image update visible in source control.

Reader next step

Choose one non-production deployment that a coding agent recently edited and inventory every effective image reference. Before asking for a patch, write a change-scope note naming the registry, release tag, platforms, signer policy, files in scope, and previous digest.

Then have the agent resolve the proposed image, prepare one digest-only patch, and produce a reviewable diff . Run the happy path above, save the sanitized evidence, and deliberately trigger one error-path check in a test branch. Once the team can show that a moved tag or mismatched identity blocks the merge, turn the workflow into a required repository check.