Push an image

Push an image, a Helm chart or any other OCI artifact to a repository, creating the repository on the first push if you may.

Last updated 18 November 2026View as Markdown

Replace org-example1234.ecr.example.com with your registry host, my-app with the repository name and v1.2.0 with the tag.

Prerequisites

  • Logged in to the registry (see Log in to the registry).
  • Permission for ecr:PushImage on the repository. To push to a name that has no repository yet, ecr:CreateRepository instead.
  • From a CI job logged in with its GITHUB_TOKEN: packages: write in the workflow, and a new name only inside a registry alias's namespace (see Log in to the registry).

Push

  1. Open Image repositories, then open the repository.
  2. Open the Push commands tab. It shows the login, build, tag, push and pull commands with your registry host and the repository filled in.

Opening the repository's page needs ecr:DescribeRepositories on it.

docker tag my-image:latest org-example1234.ecr.example.com/my-app:v1.2.0
docker push org-example1234.ecr.example.com/my-app:v1.2.0

Any OCI client works the same way:

helm push chart-0.1.0.tgz oci://org-example1234.ecr.example.com/charts
oras push org-example1234.ecr.example.com/team/config:v1 file.yaml

Result

The image is listed on the repository's Images tab, and a scan of it starts (see Scan an image); Helm charts, signatures, SBOMs and multi-platform indexes are not scanned. An ECR Image Action event with action-type PUSH goes to your event bus.

Pushing to a name that has no repository creates it, private, on the first push. Without ecr:CreateRepository the push is refused instead.

If the push is refused

  • DENIED token does not grant push on repository my-app: the credential may not push here, or, for a new name, may not create the repository.
  • DENIED storage quota exceeded: repository my-app stores … (a repository's own cap) or storage quota exceeded: the organization stores … (the organization's own cap); when the platform's registry storage quota is the limit, the message starts with Quota exceeded:. See Set a storage quota.
  • DENIED with a message starting Quota exceeded: when a push to a new name would pass the organization's repository quota (see Quotas).
  • TAG_INVALID tag "v1.2.0" is immutable in this repository and already points at a different image; …: see Make tags immutable.
  • DENIED dockerhub/node is a pull-through cache of …; push to another repository: a pull-through cache repository cannot be pushed to.
  • NAME_INVALID for a repository name the registry does not accept (see Repositories, tags and images).
  • SIZE_INVALID (413) for a manifest over 4 MiB.
Did this page help you?