Guides

How to Push a Docker Image to Amazon ECR (Step by Step)

By Ravindra Bagale, AWS & DevOps trainer · LinkedIn · Published: 16 October 2026 · Last updated: 17 October 2026

To push a Docker image to Amazon ECR: create a repository, log in with aws ecr get-login-password | docker login, tag the image with the full ECR URI (ACCOUNT.dkr.ecr.REGION.amazonaws.com/REPO:TAG), and run docker push. The account, region and repository in the tag must match the ones you logged in to. Most errors come from a mismatch there, or from missing IAM permissions.

aws ecr create-repository --repository-name orders-api --region ap-south-1
aws ecr get-login-password --region ap-south-1 | \
  docker login --username AWS --password-stdin 123456789012.dkr.ecr.ap-south-1.amazonaws.com
docker tag orders-api:2.4.1 123456789012.dkr.ecr.ap-south-1.amazonaws.com/orders-api:2.4.1
docker push 123456789012.dkr.ecr.ap-south-1.amazonaws.com/orders-api:2.4.1

A live example first

We have built orders-api:2.4.1 on an EC2 instance in Mumbai (ap-south-1). The AWS account ID here is the documentation example 123456789012. Use yours from aws sts get-caller-identity.

1. Create the repository with scanning and immutable tags turned on:

aws ecr create-repository \
  --repository-name orders-api \
  --image-scanning-configuration scanOnPush=true \
  --image-tag-mutability IMMUTABLE \
  --region ap-south-1

"repositoryUri": "123456789012.dkr.ecr.ap-south-1.amazonaws.com/orders-api"

2. Log in:

aws ecr get-login-password --region ap-south-1 | docker login --username AWS \
  --password-stdin 123456789012.dkr.ecr.ap-south-1.amazonaws.com

Login Succeeded

3. Tag and push:

docker tag orders-api:2.4.1 123456789012.dkr.ecr.ap-south-1.amazonaws.com/orders-api:2.4.1
docker push 123456789012.dkr.ecr.ap-south-1.amazonaws.com/orders-api:2.4.1

The push refers to repository [123456789012.dkr.ecr.ap-south-1.amazonaws.com/orders-api]
5f70bf18a086: Pushed
2.4.1: digest: sha256:3c1f...9ab2 size: 1784

4. Check:

aws ecr describe-images --repository-name orders-api --region ap-south-1 \
  --query 'imageDetails[].imageTags'

Done. Friends, notice that the tag itself tells Docker where to send the image. That is why the full URI matters.

How does pushing to ECR work?

Docker does not know about AWS. It only knows registries and logins. get-login-password asks AWS for a temporary password (valid for 12 hours) using your IAM identity, and docker login saves it for that registry address. When you push, Docker reads the registry address from the tag and uploads the layers there. Layers that already exist are skipped, so the second push is fast.

How do I push step by step?

1. Run aws sts get-caller-identity and note the account ID.
2. Pick a region and stay with it.
3. Create the repository once.
4. Log in with get-login-password.
5. Tag the image with the full URI.
6. Push.
7. Check with describe-images or the console.

IAM permissions for pushing

Attach a policy like this to the CI role or user (narrowed to one repository):

{
  "Version": "2012-10-17",
  "Statement": [
    { "Effect": "Allow", "Action": "ecr:GetAuthorizationToken", "Resource": "*" },
    { "Effect": "Allow",
      "Action": ["ecr:BatchCheckLayerAvailability", "ecr:InitiateLayerUpload",
                 "ecr:UploadLayerPart", "ecr:CompleteLayerUpload", "ecr:PutImage"],
      "Resource": "arn:aws:ecr:ap-south-1:123456789012:repository/orders-api" }
  ]
}

GetAuthorizationToken must be on *. The upload actions can be limited to one repository.

Push from CI, one tool at a time

GitHub Actions (with OIDC, no stored keys)

- uses: aws-actions/configure-aws-credentials@v4
  with:
    role-to-assume: arn:aws:iam::123456789012:role/gha-ecr-push
    aws-region: ap-south-1
- uses: aws-actions/amazon-ecr-login@v2
- run: |
    docker build -t $ECR/orders-api:${{ github.sha }} .
    docker push $ECR/orders-api:${{ github.sha }}

Jenkins on EC2

Give the Jenkins EC2 instance an IAM role with the policy above, and run the same four commands in a shell step. Do not save access keys in Jenkins.

GitLab CI

Use GitLab's OIDC token with an IAM role, or a short-lived role from a runner on EC2.

Common errors and fixes

Keep the registry clean and safe

1. Turn on scan on push, or enhanced scanning with Amazon Inspector.
2. Turn on tag immutability, so 2.4.1 always means the same image.
3. Add a lifecycle policy to delete untagged images after 7 days.
4. Keep repositories private. Use ECR Public only for images you really want to share.
5. Use pull-through cache rules to copy Docker Hub images into ECR and avoid rate limits.

The same on other clouds

Real example: why private registries matter

In April 2019, Docker Hub disclosed unauthorised access to a database holding data for about 190,000 accounts, including some GitHub and Bitbucket tokens used for automated builds. Docker asked affected users to change passwords and reconnect their links. A private registry such as ECR, controlled by your own IAM roles with short-lived tokens, limits the damage when any one service has a breach.

Summary table