fix(ecs): support digest references in TagParameterContainerImage via imageDigest option

[Zelys-DFKH]

Closes #37718.

Credit to @nguyengg for filing this with a clear diagnosis, and to @pahud for the key insight that repositoryUriForTagOrDigest() can't be used here because CfnParameter.valueAsString is an unresolved CloudFormation token at synth time — the startsWith('sha256:') check always fails.

Reason for this change

TagParameterContainerImage.bind() always calls repositoryUriForTag(), which produces a colon separator between the repository URI and the parameter value. When the parameter holds a digest (sha256:...), the correct separator is @. The naive fix of switching to repositoryUriForTagOrDigest() doesn't work because that method resolves the tag/digest at synth time using startsWith('sha256:'), but CfnParameter.valueAsString is an unresolved token — so it always falls through to the tag path.

Description of changes

Adds an optional imageDigest?: boolean prop to TagParameterContainerImage (default: false, fully backward-compatible). When true, bind() calls repositoryUriForDigest() instead of repositoryUriForTag(), producing the correct @ separator in the synthesized CloudFormation template. Also updates the JSDoc for tagParameterName and tagParameterValue to reflect that the parameter may hold a digest as well as a tag.

Describe any new or updated permissions being added

None.

Description of how you validated changes

Two new unit tests in tag-parameter-container-image.test.ts:

• Default (imageDigest: false / omitted): asserts the synthesized Image property uses : separator
• imageDigest: true: asserts the synthesized Image property uses @ separator

All existing tests continue to pass.

Checklist

• My code adheres to the CONTRIBUTING guide
• I have tested this locally where applicable
• This PR fixes a bug (non-breaking change that fixes an issue)

By submitting this pull request, I confirm that my contribution is made under the terms of the Apache-2.0 license

[aws-cdk-automation]

The pull request linter fails with the following errors:

❌ Fixes must contain a change to an integration test file and the resulting snapshot.

If you believe this pull request should receive an exemption, please comment and provide a justification. A comment requesting an exemption should contain the text Exemption Request. Additionally, if clarification is needed, add Clarification Request to a comment.

✅ A exemption request has been requested. Please wait for a maintainer's review.

[Zelys-DFKH]

Exemption Request

The linter is right to flag this: integration tests catch gaps unit tests miss. This isn't one of those cases.

Per AGENTS.md, integration tests are required for new CFN resource types, new CFN properties, and custom resources. This PR adds none of those. imageDigest is a CDK-level construct option that determines which existing ECR repository method runs at synth time: repositoryUriForDigest() instead of repositoryUriForTag(). The only observable difference in the synthesized template is the separator character in an existing Fn::Join: @ instead of :.

Two unit tests assert the synthesized template produces the correct separator for each case. That's the exact coverage an integration test would also verify, without deploying anything new to CloudFormation.