# IAM policy: push and pull one ECR repository

IAM policy examples · Updated 17 November 2026

**Short answer:** Allow ecr:GetAuthorizationToken on "*" (it has no resource), and the layer and image actions (BatchCheckLayerAvailability, InitiateLayerUpload, UploadLayerPart, CompleteLayerUpload, PutImage, plus BatchGetImage and GetDownloadUrlForLayer for pulls) on the repository ARN.

## The policy

```
{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "GetLoginToken",
      "Effect": "Allow",
      "Action": "ecr:GetAuthorizationToken",
      "Resource": "*"
    },
    {
      "Sid": "PushAndPullOneRepo",
      "Effect": "Allow",
      "Action": [
        "ecr:BatchCheckLayerAvailability",
        "ecr:InitiateLayerUpload",
        "ecr:UploadLayerPart",
        "ecr:CompleteLayerUpload",
        "ecr:PutImage",
        "ecr:BatchGetImage",
        "ecr:GetDownloadUrlForLayer"
      ],
      "Resource": "arn:aws:ecr:eu-west-2:123456789012:repository/orders-api"
    }
  ]
}
```

## What each action does

- `ecr:GetAuthorizationToken`: behind `aws ecr get-login-password`. The token is account-wide, so the action can't be scoped to a repository. It doesn't grant access to any repository by itself.
- `BatchCheckLayerAvailability`: Docker asks which layers already exist so it only uploads new ones.
- `InitiateLayerUpload`, `UploadLayerPart`, `CompleteLayerUpload`: the layer upload.
- `PutImage`: writes the manifest and the tag. This is the step that makes the push visible.
- `BatchGetImage`, `GetDownloadUrlForLayer`: pulling, which multi-stage builds and cache-from need.

## Use it in CI

```
aws ecr get-login-password --region eu-west-2 | docker login \
  --username AWS --password-stdin 123456789012.dkr.ecr.eu-west-2.amazonaws.com

docker push 123456789012.dkr.ecr.eu-west-2.amazonaws.com/orders-api:1.4.2

aws ecr describe-images --repository-name orders-api \
  --query 'imageDetails[].imageTags' --output text
```

For GitHub Actions, attach the policy to the role in the [OIDC trust policy](https://cloudconsole.dev/iam/github-actions-oidc) instead of storing keys. Add `ecr:DescribeImages` on the repository if a later step reads the result.

## Variations

- **Pull only** (ECS, EKS nodes, Lambda container images): keep `GetAuthorizationToken`, `BatchGetImage`, `GetDownloadUrlForLayer` and `BatchCheckLayerAvailability`. For ECS this goes on the [task execution role](https://cloudconsole.dev/iam/ecs-task-role-vs-execution-role).
- **Cross-account pull**: add a repository policy in the image account allowing the other account's role the pull actions; the puller also needs them in IAM.
- **Immutable tags**: turn on tag immutability so a compromised CI job can't overwrite a released tag, even with `PutImage`.
- **Pull-through cache** repositories need extra actions to create the cached repository on first pull; see the ECR docs.

## Scan and lifecycle

A CI role with push rights doesn't need permission to configure scanning or lifecycle rules; set those once on the repository with an admin role. Lifecycle policies expire untagged and old images so a busy pipeline doesn't grow storage forever, and basic or enhanced scanning reports vulnerabilities on push.

```
aws ecr put-lifecycle-policy --repository-name orders-api \
  --lifecycle-policy-text file://keep-last-50.json
```

Keep push rights to CI only. Developers usually need pull access at most, and production pulls should come from the execution or node role rather than a person's credentials.

## Common mistakes

- **GetAuthorizationToken scoped to the repository ARN**: login fails with AccessDenied even though the repository statements are right.
- **`no basic auth credentials`** on push means Docker never logged in, or logged in to a different registry or region; see [the error page](https://cloudconsole.dev/errors/ecr-no-basic-auth-credentials).
- **Repository encrypted with a customer managed KMS key**: pushers and pullers also need the matching KMS permissions.
- **Using `AmazonEC2ContainerRegistryFullAccess`** in CI: it can delete repositories and change their policies.

## Questions

### What permissions are needed to push to ECR?

ecr:GetAuthorizationToken on "*", and BatchCheckLayerAvailability, InitiateLayerUpload, UploadLayerPart, CompleteLayerUpload and PutImage on the repository.

### Why does ecr:GetAuthorizationToken need Resource "*"?

The token authenticates you to the whole registry, not one repository, so the action has no resource ARN. Repository access is still controlled by the other statements.

## When this happens away from your desk

A push that failed means a deploy that never happened. Checking the latest image tag in the repository from your phone tells you whether the build or the deploy is the stage to look at.

[About the CloudConsole app](https://cloudconsole.dev/aws-console-app) · [Download on the App Store](https://apps.apple.com/app/cloudconsole-for-aws/id6835419710)

## Sources

- [Amazon ECR documentation](https://docs.aws.amazon.com/ecr/)
- [Actions, resources, and condition keys for Amazon Elastic Container Registry](https://docs.aws.amazon.com/service-authorization/latest/reference/list_amazonelasticcontainerregistry.html)

## Related

- [aws ecr get-login-password](https://cloudconsole.dev/cli/ecr-get-login-password)
- [no basic auth credentials when pushing to Amazon ECR](https://cloudconsole.dev/errors/ecr-no-basic-auth-credentials)
- [GitHub Actions OIDC: IAM role trust policy](https://cloudconsole.dev/iam/github-actions-oidc)
- [ECS task role vs task execution role](https://cloudconsole.dev/iam/ecs-task-role-vs-execution-role)
- [CodeBuild service role permissions](https://cloudconsole.dev/iam/codebuild-service-role)
- [aws ecr describe-images](https://cloudconsole.dev/cli/ecr-describe-images)

---

Source: https://cloudconsole.dev/iam/ecr-push-pull

CloudConsole is an independent iPhone and Android app for Amazon Web Services by Cloudconcur Ltd. It is not affiliated with Amazon Web Services.
