Context
An image push fails because the release tag already exists. Under pressure, an engineer disables immutability, pushes again, and gets a green pipeline. The release label now points to different bytes from the artifact that was reviewed earlier. ECR tag immutability is useful precisely because it forces the team to resolve this ambiguity. A collision should trigger an identity check, not an automatic overwrite.
Establish the release identity
Amazon ECR supports tag immutability settings that prevent covered tags from being overwritten. Review the repository's actual mutability configuration, including any supported exclusions, in the current AWS documentation. A descriptive tag is useful for people, while an image digest identifies the stored image content. Your release process should retain both and make clear which identity the deployment consumes.
Choose a release identifier that represents one intended artifact. A short branch name such as production is a moving pointer by design and should not double as immutable evidence of a specific build. A commit identifier helps trace source, but source identity alone does not guarantee identical output when dependencies, build arguments, or base images can change.
An illustrative conflicting rerun
Consider a pipeline that tags images with an application version. The first attempt builds successfully and pushes the image, then fails while uploading a report. A later rerun rebuilds with a newly resolved base image and tries to push the same version. ECR rejects it. The collision reveals that the supposed retry produced a different artifact.
Inspect the existing digest and the intended build record. Determine whether the earlier image passed the required checks and whether its provenance matches the release. If it is the correct artifact, continue from that artifact rather than rebuilding casually. If it is wrong, create a new release identity and document why the previous candidate is rejected.
Separate building from promotion
Build once for a release candidate and retain the resulting digest, build inputs, test results, and relevant attestations. Promotion should select the approved artifact for another environment. It should not silently repeat compilation and dependency resolution under the same label.
Where images must be copied between repositories or accounts, verify the resulting artifact identity using the tooling and image format involved. Preserve evidence that the promoted object corresponds to the reviewed candidate. For multi-platform images, record the image index and the relevant platform manifests so operators understand what the target architecture will actually pull.
Define retry behaviour explicitly
A push retry after a lost response is different from a new build. If the registry already contains the expected artifact, the pipeline can report that the desired state is present after verifying identity. It should not convert every “tag exists” response into success without checking the stored object.
Design the job so it can resume after the push boundary. Save the release record before later steps that may fail, and make report publication repeatable. If the build artifact is unavailable on rerun, require an explicit decision about rebuilding instead of pretending the new output is automatically the original candidate.
Review repository policy and permissions
Identify who may change tag mutability, delete images, or push release tags. The protection is weakened if the normal deployment identity can casually remove the existing tag and replace it. Align repository permissions with the intended separation between producing artifacts and deploying them.
Review cleanup policies alongside release retention. An immutable tag does not help rollback if a separate lifecycle policy removes the underlying artifact. Retain currently deployed and approved rollback digests for the intended operational window. Test that the release inventory and cleanup rules agree rather than relying on the visual appearance of tags in the console.
Deploy and verify by digest
Make the deployment record name the approved digest. Check the image identity observed by the runtime after rollout, not just the value printed by the build job. A deployment template may still reference an old moving tag, or a later configuration layer may override the intended image.
Verify application health and the release identifier exposed by a suitable diagnostic endpoint or internal command. Artifact identity and functional acceptance answer different questions. A correct digest can still contain a defective release; a healthy endpoint can still belong to the wrong release. Keep both pieces of evidence in the deployment receipt.
Test collision and rollback scenarios
In a non-production repository, publish a candidate and attempt to publish different content under the same protected tag. Confirm the failure is visible and the original artifact remains unchanged. Then simulate a pipeline failure immediately after a successful push and verify the resume path checks the existing digest.
Rehearse rollback to a retained digest after several newer releases. Confirm permissions, runtime access, and supporting configuration still allow the older artifact to run. Database and external service compatibility need their own rollback assessment; selecting old application bytes does not reverse durable data changes.
Quick diagnostic map
| Evidence | Interpretation | Next check |
|---|---|---|
| Tag already exists | Candidate identity conflict | Compare stored digest |
| Rerun changes bytes | Mutable build input | Retain original candidate |
| Rollback image missing | Retention mismatch | Review lifecycle policy |
A focused operator exercise
Publish a synthetic release candidate and retain its source revision, dependency inputs, image digest, and test receipt. Attempt to push different content under the same protected tag in the test repository. Confirm the collision remains visible and the original stored artifact is unchanged. Record the intended operator response rather than allowing automatic policy weakening.
Simulate failure after a successful push but before the pipeline records overall success. Resume through the designed continuation path and verify it compares the existing digest before accepting the release. Then deliberately rebuild with a changed input and confirm the pipeline identifies a new candidate instead of treating the same source revision as proof of identical output.
Deploy the accepted digest to a test runtime and read back its observed image and application release identity. Perform a rollback to the previous retained digest after another candidate is published. The receipt should connect each runtime state to the artifact that passed testing. Review cleanup rules afterward to ensure those retained rollback objects remain available for the intended window.
Turn the error into a useful control
A collision report should include the release label, existing digest, intended digest when available, build identifiers, and the decision required. Avoid a generic instruction to disable immutability. Support engineers should know when they can resume a verified artifact and when the release owner must create a new candidate.
Clouvenix can help connect ECR policy, CI artifact records, and runtime verification. The practical benefit is a release label that remains trustworthy and a deployment process that promotes the artifact the team actually approved.
Explore Clouvenix devops automation for implementation and operational handover.