Introduction
Strictly speaking, Amazon ECS does not host Docker images. ECS runs containers, while Amazon ECR stores the container images that ECS tasks pull at deployment time. So when people say "push a Docker image to an ECS repository," the repository they actually mean is almost always ECR.
The workflow is simple: create or choose an ECR repository, log Docker in to ECR, tag the image with the repository URI, and push it. After that, reference the image URI from your ECS task definition or service.
Build or Choose the Local Image
Start with a local Docker image. For example:
docker build -t my-app:latest .
You can confirm it exists with:
If the image was already built by CI or another process, you can skip this step and use the existing local tag.
Create an Amazon ECR Repository
If the repository does not exist yet, create it with the AWS CLI:
aws ecr create-repository --repository-name my-app --region us-east-1
The response includes the repository URI, which looks like this:
123456789012.dkr.ecr.us-east-1.amazonaws.com/my-app
That URI is what Docker needs for tagging and pushing.
Authenticate Docker to ECR
Before Docker can push to ECR, log in with an ECR authorization token:
aws ecr get-login-password --region us-east-1 \
| docker login --username AWS --password-stdin 123456789012.dkr.ecr.us-east-1.amazonaws.com ``` This authentication is temporary, so CI pipelines and developer machines usually run it before each push. If this step fails, the most common causes are wrong AWS credentials, wrong region, or missing ECR permissions. ## Tag the Image with the ECR URI Docker pushes tags, not abstract image names. Tag the local image with the full repository URI: ```bash docker tag my-app:latest 123456789012.dkr.ecr.us-east-1.amazonaws.com/my-app:latest ``` If you want a versioned image instead of `latest`, use a more explicit tag: ```bash docker tag my-app:latest 123456789012.dkr.ecr.us-east-1.amazonaws.com/my-app:2025-09-23 ``` Versioned tags are usually safer in production because they make deployments reproducible. ## Push the Image Now push the image to ECR: ```bash docker push 123456789012.dkr.ecr.us-east-1.amazonaws.com/my-app:latest ``` Once the push succeeds, the image is stored in ECR and available for ECS task definitions to pull. You can verify the image is there with: ```bash aws ecr describe-images --repository-name my-app --region us-east-1 ``` ## Use the Image from ECS After the image is in ECR, point your ECS task definition at the ECR image URI: ```json { "containerDefinitions": [ { "name": "my-app", "image": "123456789012.dkr.ecr.us-east-1.amazonaws.com/my-app:latest", "essential": true } ] } ``` That is the connection between ECR and ECS: ECR stores the image, ECS runs it. ## A Full Example Sequence A minimal end-to-end shell session looks like this: ```bash docker build -t my-app:latest . aws ecr create-repository --repository-name my-app --region us-east-1 aws ecr get-login-password --region us-east-1 \ | docker login --username AWS --password-stdin 123456789012.dkr.ecr.us-east-1.amazonaws.com docker tag my-app:latest 123456789012.dkr.ecr.us-east-1.amazonaws.com/my-app:latest docker push 123456789012.dkr.ecr.us-east-1.amazonaws.com/my-app:latest ``` In CI, those are the same core steps even if the surrounding tooling is GitHub Actions, GitLab CI, Jenkins, or CodeBuild. ## Common Pitfalls The biggest pitfall is the naming confusion in the title itself: ECS is the orchestrator, ECR is the image registry. If you look for an "ECS repository," you are usually looking for ECR documentation. Another common issue is a region mismatch. The repository URI, the `aws ecr get-login-password` command, and the task definition image reference must all point at the same AWS region. Authentication failures are also common. The AWS identity used for the push needs ECR permissions such as creating repositories, getting authorization tokens, and pushing image layers. Developers also rely too heavily on the `latest` tag. That works, but immutable version tags are easier to trace, roll back, and audit. Finally, make sure the ECS task execution role can pull from ECR. Pushing the image successfully is only half of the deployment story. ## Summary - The image repository for ECS workloads is Amazon ECR, not ECS itself. - Build the image locally, then create or choose an ECR repository. - Authenticate Docker with `aws ecr get-login-password` and `docker login`. - Tag the image with the full ECR repository URI before pushing. - After the push, use that same ECR image URI in your ECS task definition.
