Push Docker images to CloudRepo
Docker pushes to CloudRepo like it pushes to any registry: log in once to your organization’s host, then push an image whose name carries the repository. This page is for the person or pipeline that publishes images. To pull them, see Pull Docker images.
Before you start
Section titled “Before you start”- A Docker repository, as a hosted repository (not a proxy and not a group). If you have none, create one.
- A repository token that reaches it, with Download and publish packages. A Download packages token can pull but not push.
See Repository tokens to create one. Use a token that
starts with
crp_v1_, or an organization token, which starts withcrk_v1_: a token thatnpm loginwrote (crn_v1_) does not authenticate at Docker. - Your repository’s image name:
<organization>.mycloudrepo.io/repositories/<repository>/<image>:<tag>. The organization’s name is the first part of your CloudRepo host, and the repository’s name is the one the admin portal shows. The repository’s Connection Settings show the name with your values filled in.
Push an image
Section titled “Push an image”1. Log in to the host. Pipe the token to docker login on standard input. CloudRepo does not check
the username for Docker, but use your email address.
echo "$CLOUDREPO_TOKEN" | docker login your-org.mycloudrepo.io \ --username you@example.com \ --password-stdinExpected: Login Succeeded.
2. Build and push. The image name carries the repository: the host, the literal repositories/
segment, your repository, then the image and its tag.
docker build -t your-org.mycloudrepo.io/repositories/your-repo/my-app:1.0.0 .docker push your-org.mycloudrepo.io/repositories/your-repo/my-app:1.0.0To push an image you already have, give it that name first:
docker tag my-app:1.0.0 your-org.mycloudrepo.io/repositories/your-repo/my-app:1.0.03. Check that it landed. Ask the registry for the image you pushed:
docker pull your-org.mycloudrepo.io/repositories/your-repo/my-app:1.0.0Expected: Docker finishes without an error and prints a Digest: line. The image is also listed in the
repository in the admin portal.
Push from CI
Section titled “Push from CI”Keep the token in your CI’s secret store, expose it as the environment variable CLOUDREPO_TOKEN, and
use the same login:
echo "$CLOUDREPO_TOKEN" | docker login your-org.mycloudrepo.io \ --username you@example.com \ --password-stdin--password-stdin is Docker’s option for reading the password from standard input instead of the
command line. Never commit the token. The variable’s name is yours to choose: the admin portal’s
ready-made GitHub Actions and GitLab CI snippets call it CLOUDREPO_PASSWORD, and the value is the same
repository token either way. The portal’s
Connection Settings show those snippets with
your names filled in.
To install private Maven, Python or npm packages inside a docker build, hand the token to that build step
as a build secret, never as a build argument. See
Docker repositories, “Install packages from CloudRepo in a Docker build”.
Pushing a tag again
Section titled “Pushing a tag again”By default, pushing a tag that already exists points that tag at the image you pushed. So give each
release its own tag, and treat a tag like latest as one that moves. To lock your release tags, turn on
Immutable Tags.
A Docker repository has no Overwrite Protection, the setting Maven, Python and npm repositories have, and that card does not appear in its settings. Immutable Tags is Docker’s equivalent.
Immutable Tags
Section titled “Immutable Tags”Immutable Tags locks the tags of a hosted Docker repository. While it is on, a release tag keeps the image you released. It is off until you turn it on, one repository at a time. To turn it on, open the repository, click Settings, and turn on the Immutable Tags card. It is offered to people who can manage repositories.
While Immutable Tags is on:
- A pushed tag keeps its image. A push of a different image to that tag is refused with
409 Conflict, the error codeTAG_INVALIDand, for a tag namedv1, the messagetag v1 is immutable in this repository; push a new tag. Push the new image under a new tag. - Pushing the same image again still works. The same image means the same digest, so a retried push of one build lands. A rebuilt image usually gets a new digest, and a locked tag refuses it as it refuses any different image. If your CI rebuilds on every run, push each build under a new tag.
- A locked tag cannot be deleted, from a registry client or from the admin portal. The answer is
409 Conflictwithtag v1 is immutable in this repository; it cannot be deleted. lateststill moves, and so do cosign’s tags. cosign keeps a signature, an attestation or an SBOM undersha256-<digest>.sig,.attor.sbom, and a baresha256-<digest>tag. Those stay movable, so you can sign and attest an image again.
To turn it off, turn off the Immutable Tags card. CloudRepo asks you to confirm your identity first, because every tag can move again once it is off.
Webhooks on push and delete
Section titled “Webhooks on push and delete”A CloudRepo webhook can start a job when an image lands or goes. Create it as Webhooks describes: choose your Docker repository and tick Upload, Delete or both.
- A push fires the Upload webhooks. A tag push sends an
upload-completeevent to the repository’s Upload webhooks. Itsfile-nameis the image and the tag, such asmy-app:1.0.0, and itsfile-pathis empty. A push by digest, a layer upload and a pull fire no webhook. - A tag delete fires the Delete webhooks. Deleting a tag in the admin portal, or from a registry client,
sends a
delete-file-completeevent to the repository’s Delete webhooks. Itsfile-nameis the image and the tag, such asmy-app:1.0.0. A delete that is refused or fails sends none.
Coming from Artifactory or Nexus? Move Artifactory and Nexus webhooks to CloudRepo maps each of their events and payload fields to these.
When a push is refused
Section titled “When a push is refused”Check these in order:
docker loginanswers 401 Unauthorized. Use a repository token as the password, not the password you sign in to the admin portal with. Check on the Repository Tokens page that the token has not been revoked or expired. A token fromnpm login(crn_v1_) is refused here.docker pushanswers 403 after a successful login. The token cannot push to this repository. Pushing needs a Download and publish packages token that reaches this repository, and the user who created the token must have read and write access, not read only. Check the token’s access on the Repository Tokens page.docker pushis refused with 405. The repository is a group or a proxy. CloudRepo answers a push to a group withWrites are not permitted to group repositories, and a push to a proxy repository withWrites are not permitted to remote repositories: hereremotemeans a proxy. A group has no storage of its own, and a proxy repository takes no push either. Push to a hosted repository directly. A group that lists that repository as a member serves the image. If your CI pushed to a Nexus group through its writable member, push to that hosted member and pull through the group, as the terms page maps.docker pushof a tag that already exists is refused. The repository has Immutable Tags on, and the tag names another image. CloudRepo answers409 ConflictwithTAG_INVALID. Push the image under a new tag.- Docker cannot find the repository, or the registry refuses the name. Check that the image name
carries the literal
repositories/segment, as in step 2: a name without it is refused as invalid (NAME_INVALID). A good login cannot tell you the name is wrong, becausedocker loginnames no repository.
More: Repository tokens, for every client’s credential; Pull Docker images, for the other direction; and Docker repositories, for groups and the other settings.