# 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.

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](log-in.md)).
- 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](log-in.md)).

## Push

**Console**
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.

```sh
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:

```sh
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](scan-an-image.md)); 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](set-a-storage-quota.md).
- `DENIED` with a message starting `Quota exceeded:` when a push to a new name would pass the
  organization's repository quota (see [Quotas](quotas.md)).
- `TAG_INVALID` `tag "v1.2.0" is immutable in this repository and already points at a different image; …`:
  see [Make tags immutable](make-tags-immutable.md).
- `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](repositories-and-images.md)).
- `SIZE_INVALID` (`413`) for a manifest over 4 MiB.

## Related

- [Pull an image](pull-an-image.md)
- [Create a repository](create-a-repository.md)
