Introduction

When people say they want to push an image to an "ECS repository," they usually mean Amazon ECR, the container registry used by ECS tasks and services. The workflow is simple: build the image, create or identify the ECR repository, authenticate Docker against ECR, tag the image with the repository URI, and push it.

Build the Image and Create the Repository

First, build a local Docker image:

docker build -t my-app:latest .

If the ECR repository does not exist yet, create it:

aws ecr create-repository --repository-name my-app --region us-east-1

This returns repository details including the full repository URI, which looks like:

123456789012.dkr.ecr.us-east-1.amazonaws.com/my-app

That URI is what Docker needs for tagging and pushing.

Authenticate Docker to Amazon ECR

Before pushing, Docker must log in to the registry:

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

This step is required because ECR is a private registry by default. If authentication fails, the push will fail even when the image and repository names are correct.

Make sure the AWS CLI is already configured with credentials and a role or user that has ECR push permissions. At minimum, the identity needs permission for authentication and image upload actions on the repository. Region mismatches are also common, so verify that the login region, repository region, and image URI all match.

Tag and Push the Image

Now tag the local image with the ECR repository URI:

docker tag my-app:latest 123456789012.dkr.ecr.us-east-1.amazonaws.com/my-app:latest

Then push it:

docker push 123456789012.dkr.ecr.us-east-1.amazonaws.com/my-app:latest

After the push completes, the image is available for ECS task definitions and services.

It is common to use a versioned tag instead of only latest:

docker tag my-app:latest 123456789012.dkr.ecr.us-east-1.amazonaws.com/my-app:2026-03-07
docker push 123456789012.dkr.ecr.us-east-1.amazonaws.com/my-app:2026-03-07

Versioned tags make deployments traceable and reduce confusion during rollbacks.

Verify the Push and Use It in ECS

You can verify that the image reached ECR:

aws ecr describe-images --repository-name my-app --region us-east-1

Then reference that exact image tag in the ECS task definition:

1{
2  "containerDefinitions": [
3    {
4      "name": "my-app",
5      "image": "123456789012.dkr.ecr.us-east-1.amazonaws.com/my-app:2026-03-07",
6      "essential": true
7    }
8  ],
9  "family": "my-app-task"
10}

ECS itself does not store images. It pulls them from ECR when tasks start. That is why pushing to the correct ECR repository is the actual deployment prerequisite.

If the task definition already exists, the next step is usually to register a new revision and update the ECS service so it starts tasks from the newly pushed image. The push is only the registry step, not the full deployment step.

Common Pitfalls

The biggest mistake is confusing ECS and ECR. ECS runs containers. ECR stores images. You do not push images to ECS directly.

Another common issue is tagging the image incorrectly. If the repository URI is wrong, Docker will either push to the wrong place or fail with a repository-not-found error.

Authentication problems are also frequent. If docker login was skipped or the AWS identity lacks ECR permissions, the push is rejected.

Finally, avoid relying only on the latest tag in real environments. Immutable version tags make debugging and rollback much easier.

Summary

• Build the Docker image locally first.
• Create or identify the target ECR repository.
• Authenticate Docker to ECR with aws ecr get-login-password.
• Tag the image with the full ECR repository URI and push it.
• Reference the pushed ECR image from your ECS task definition.