aws ecr create-repository: Usage & Common CI Errors

Create an Amazon ECR repository to hold your container images.

aws ecr create-repository provisions a new ECR repository. In CI it is often run idempotently before the first push, with scan-on-push and tag immutability enabled.

What it does

aws ecr create-repository --repository-name <name> creates a private image repository and returns its URI. Flags enable image scanning on push (--image-scanning-configuration), enforce immutable tags (--image-tag-mutability IMMUTABLE), and set encryption. Unlike Docker Hub, ECR does not auto-create a repo on first push - it must exist first.

Common usage

# Create a repo with scan-on-push and immutable tags
aws ecr create-repository \
  --repository-name my-app \
  --image-scanning-configuration scanOnPush=true \
  --image-tag-mutability IMMUTABLE

# Idempotent create in CI: ignore "already exists"
aws ecr describe-repositories --repository-names my-app \
  || aws ecr create-repository --repository-name my-app

Common error in CI: RepositoryAlreadyExistsException

Re-running the create step fails the pipeline with "An error occurred (RepositoryAlreadyExistsException) when calling the CreateRepository operation". Fix: make it idempotent - guard the create with aws ecr describe-repositories --repository-names <name> || aws ecr create-repository ..., or manage the repo in Terraform so CI only pushes. A separate failure, "name with namespace ... is invalid", means an uppercase or illegal character in the repo name (ECR names must be lowercase).

Key options

Related guides