fix: pre-set ECR Lambda pull policy to prevent concurrent SetRepositoryPolicy race condition (#8190)

[abhishektang]

Problem

Fixes #8190.

When deploying a SAM application with multiple Lambda functions referencing the same or different ECR repositories, CloudFormation calls ecr:SetRepositoryPolicy concurrently — once per Lambda. Each call overwrites the existing policy rather than merging it, so whichever write lands last wins and earlier Lambdas lose access, resulting in a 403 on image pull.

Solution

Before creating the changeset, SAM CLI now pre-sets a stable SAMCliLambdaECRAccess policy SID on every ECR repository referenced by the deployment (via ImageRepository / ImageRepositories). Because the SID is deterministic, repeated calls are idempotent and safe.

Three private helpers are added to samcli/commands/deploy/deploy_context.py:

Helper	Responsibility
_extract_ecr_repo_name	Parse repo name from a full ECR URI
_ensure_ecr_lambda_pull_policy	Collect all unique repo names and call _upsert_ecr_lambda_policy for each
_upsert_ecr_lambda_policy	Idempotently set or merge the SAMCliLambdaECRAccess statement; retries on concurrent SetRepositoryPolicy conflicts; skips gracefully on AccessDeniedException

_ensure_ecr_lambda_pull_policy is called from DeployContext.run() immediately before create_and_wait_for_changeset.

Changes

• samcli/commands/deploy/deploy_context.py — ECR policy helpers + call site
• samcli/commands/deploy/exceptions.py — new ECRPolicySetError(UserException)
• tests/unit/commands/deploy/test_ecr_policy_helpers.py — 21 new unit tests covering all branches of the three helpers
• tests/unit/commands/deploy/test_deploy_context.py — patch _ensure_ecr_lambda_pull_policy at class level to isolate existing deploy tests from ECR side-effects
• tests/unit/commands/_utils/test_template.py — fix test_updates_imageuri_when_pointing_to_local_archive: replace fragile CWD-relative file creation (which caused a PermissionError on macOS) with a pathlib.Path.is_file mock

Testing

pytest tests/unit/commands/deploy/test_deploy_context.py \
       tests/unit/commands/deploy/test_ecr_policy_helpers.py -v
# 35 passed

pytest --cov samcli --cov schema --cov-fail-under 94 tests/unit \
       --ignore=tests/unit/lib/cfn_language_extensions \
       --cov-config=.coveragerc_no_lang_ext
# 7479 passed, 0 failed, 94.05% coverage

Ruff and mypy also pass (mypy pre-existing errors are unrelated to this change).

[roger-zhangg]

Reviewed the full diff. This is a well-designed fix for the concurrent SetRepositoryPolicy race condition (issue #8190).

What works well:

1. Race condition prevention — Pre-setting the ECR policy before CloudFormation creates the changeset ensures Lambda always has pull access regardless of concurrent writes from CF's per-function SetRepositoryPolicy calls.

2. SID-based idempotency — Using a deterministic SAMCliLambdaECRAccess SID means repeated deploys safely replace the existing SAM-managed statement without accumulating duplicates.

3. Preserves customer policies — The code filters out only the SAM-owned SID and preserves all other existing statements in the policy document.

4. Graceful degradation — AccessDeniedException is caught and logged as a warning rather than blocking the deployment, which is the right tradeoff: users who lack ECR policy permissions might have manually configured policies already.

5. Shared-repo deduplication — The set-based dedup on repo names correctly handles multiple functions sharing a single ECR repo (the exact scenario from issue #8190).

6. Comprehensive tests — 21 new unit tests cover: URI parsing, deduplication logic, no-existing-policy, merge-with-existing, idempotent replace, access denied soft-fail, unexpected error propagation, the 7-function shared-repo scenario, and mixed repos.

Minor notes (non-blocking):

• force=False on set_repository_policy is correct — it prevents overwriting policies that include aws:PrincipalOrgID conditions, which is the safe default.
• There is a theoretical TOCTOU window between get_repository_policy and set_repository_policy, but since this runs once in the CLI before changeset creation (not concurrently), it is not a practical concern.
• The unrelated test fix in test_template.py (replacing CWD-relative file creation with a mock) is a clean improvement.

LGTM.