Skip to content

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.

  • 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 with crk_v1_: a token that npm login wrote (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.

Used on this page only, never saved. Never enter a token or password here.

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.

Terminal
echo "$CLOUDREPO_TOKEN" | docker login your-org.mycloudrepo.io \
--username you@example.com \
--password-stdin

Expected: 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.

Terminal
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.0

To push an image you already have, give it that name first:

Terminal
docker tag my-app:1.0.0 your-org.mycloudrepo.io/repositories/your-repo/my-app:1.0.0

3. Check that it landed. Ask the registry for the image you pushed:

Terminal
docker pull your-org.mycloudrepo.io/repositories/your-repo/my-app:1.0.0

Expected: Docker finishes without an error and prints a Digest: line. The image is also listed in the repository in the admin portal.

Keep the token in your CI’s secret store, expose it as the environment variable CLOUDREPO_TOKEN, and use the same login:

Terminal
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”.

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 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 code TAG_INVALID and, for a tag named v1, the message tag 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 Conflict with tag v1 is immutable in this repository; it cannot be deleted.
  • latest still moves, and so do cosign’s tags. cosign keeps a signature, an attestation or an SBOM under sha256-<digest>.sig, .att or .sbom, and a bare sha256-<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.

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-complete event to the repository’s Upload webhooks. Its file-name is the image and the tag, such as my-app:1.0.0, and its file-path is 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-complete event to the repository’s Delete webhooks. Its file-name is the image and the tag, such as my-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.

Check these in order:

  • docker login answers 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 from npm login (crn_v1_) is refused here.
  • docker push answers 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 push is refused with 405. The repository is a group or a proxy. CloudRepo answers a push to a group with Writes are not permitted to group repositories, and a push to a proxy repository with Writes are not permitted to remote repositories: here remote means 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 push of a tag that already exists is refused. The repository has Immutable Tags on, and the tag names another image. CloudRepo answers 409 Conflict with TAG_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, because docker login names 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.

View as Markdown