Promoting ECS images by digest
Promote the tested image digest rather than rebuilding or resolving a movable tag at each environment. Record the source, build run, image identity, configuration revision, and task definition together. Rollback requires a compatible known artifact and configuration, not merely changing the tag back.
Inside this article 6 sections +
A release tag is a useful label, but an image digest identifies content. If staging tests one image and production later resolves the same movable tag to another image, the release no longer corresponds to its test evidence. Digest-based promotion makes that mismatch visible and avoidable.
For an ECS service, build the application once from a reviewed revision, publish the resulting image, record its digest, and use that identity through the promotion path. Keep environment configuration separate and equally traceable so the same binary does not conceal an unexplained configuration change.
Create an evidence record at build completion
Record the immutable source revision, build workflow and run, dependency inputs, image repository, image digest, target architecture, and required test or scan reports. The digest establishes content identity; the surrounding record explains how that content was produced and why it is eligible for release.
Do not derive the production image from “latest successful build” without verifying the source and approval relationship. Two builds can finish out of order, and a branch can advance after review. Promotion should select a concrete release record, not a moving search result.
- Reviewed sourceAn immutable commit and declared build inputs define the candidate.
- Published imageThe registry digest identifies the produced content.
- Environment releaseThe selected digest is paired with configuration and task-definition revision.
- Observed tasksDeployment evidence confirms the service is running the intended release.
- Rollback candidateA retained prior digest and compatible configuration remain available.
Reference the digest explicitly
ECS task definitions support image references by digest. Generate the new task definition from a reviewed template and change only the fields intended for the release. Compare task roles, execution roles, environment variables, secrets references, resource limits, ports, and health checks as well as the image field.
{
"name": "portal",
"image": "111122223333.dkr.ecr.eu-west-1.amazonaws.com/portal@sha256:VERIFIED_IMAGE_DIGEST"
}
This is an illustrative container-definition fragment, not a complete task definition. The account and repository are examples, and VERIFIED_IMAGE_DIGEST must be replaced with the actual registry digest. A placeholder is deliberately not presented as a valid image identifier.
ECS can resolve tags to digests during supported deployments, but explicit promotion still helps the pipeline prove which image passed staging. Review the deployed platform and agent behavior rather than relying on a general assumption about tag resolution. Never allow a failed digest lookup to fall back silently to a tag.
Account for multi-architecture images
A multi-platform image can have a top-level index or manifest-list digest and separate platform-specific image digests. Record which identity the pipeline promotes and which architecture the ECS task uses. The runtime's observed image digest may correspond to a selected platform image rather than the top-level index.
Verify the relationship instead of comparing unrelated digest fields as plain strings. A release intended for ARM64 should not accidentally deploy an AMD64-only image, and a copied manifest list should retain the required platform content. Include the target architecture in build and deployment acceptance.
If images move between registries or AWS accounts, verify the destination content and permissions. Copying a tag is not sufficient evidence that every required manifest and layer arrived. Record the destination reference used by the task definition and preserve the association with the original build record.
Separate runtime configuration deliberately
Use environment-specific configuration and secret references without rebuilding the application when the architecture supports it. Version the configuration or record its effective references so a deployment can be reconstructed. A fixed image with an untracked database endpoint is not a fully identified release.
Some values are build-time inputs. Next.js public environment variables, for example, can be embedded in the browser bundle. If staging and production require different embedded values, either design an explicit runtime configuration boundary or acknowledge that the builds are different artifacts. Do not claim build-once promotion while changing public build inputs between environments.
Keep secret rotation separate from image identity, while testing their compatibility. A task may need a restart to consume a changed secret depending on how it is supplied. Record that operational behavior so a rollback does not unknowingly restore an image that expects a retired credential or configuration shape.
Verify running behavior after the update
Serialize releases to the same service according to the team's deployment policy. Two pipelines updating the service concurrently can leave the final task definition unrelated to the release a reviewer approved. Record the previous and proposed task-definition revisions before mutation.
Wait for the intended service deployment outcome and inspect task health, image identity, and application-level checks. A successful service-update API call only confirms acceptance of the update request. It does not prove every task started or that the customer operation works.
Use representative smoke checks that avoid irreversible effects. Confirm that the running application reports the expected release identity and can reach required dependencies. Keep those checks tied to the deployment record so later investigations do not rely on screenshots of a generic green dashboard.
Retain a compatible known release
Keep prior approved images available for the rollback period and protect them from an aggressive registry lifecycle rule. Retain the associated task definition and configuration references. A digest that has been deleted cannot serve as a practical rollback target.
Check database and message compatibility before restoring an old image. The previous binary may not understand data written by the new release. The secrets rotation guide explains credential transitions, and account boundaries explains deployment scope. ECS delivery implementation should make promotion and rollback equally explicit.