Skip to content
For the complete documentation index, see llms.txt. This page is also available as Markdown.
ArtifactsRegistry TypesCi Cd

Docker

Create a Docker registry, generate an identity token, then log in, push, and pull container images with the Docker CLI through Harness Artifacts.

Use a Docker registry to host private container images. The registry works with the Docker CLI.

What you will learn from this topic

By the end of this quickstart guide, you will be able to:

  • Create a registry in Harness Artifacts.

  • Publish an image to the registry.

  • Pull the image from the registry, and confirm that it works.

Before you begin

  • Install the Docker CLI (docker) on your local machine.

  • Make sure you have access to a Harness account with permission to create registries and connectors.

Create a Docker Registry

To create a Docker Registry, perform the following steps:

  1. In Artifact Registry, select Registries.

  2. Click + Create Registry.

  3. Specify the Registry name.

Registry name criteria

The registry name must start with a letter, can only contain lowercase alphanumerics, _, ., and -, and must be unique to your Harness account.

  1. Optionally, add a Description.

  2. Choose visibility between Public and Private. The default is Private.

  3. Select Docker as the Registry type.

  4. Click Save.

  5. Select Create to finalize.

Configure an upstream proxy (optional)

An upstream proxy allows your registry to fetch Docker images from external container registries when they are not available locally.

Create upstream proxy

To create an upstream proxy, perform the following steps:

  1. In Artifact Registry, select Registries.

  2. Click the drop-down next to + Create Registry and select Upstream Proxy.

  3. Specify the Registry name.

  4. Optionally, add a Description.

  5. Choose visibility between Public and Private. The default is Private.

  6. Select Docker as the Registry type.

  7. Select the Source:

    • Docker Hub: No remote registry URL required.

    • AWS ECR: Specify the Remote registry URL.

    • Custom: Specify the Remote registry URL.

  8. Select the Authentication method:

    • Docker Hub:

      • Username and password: Specify the username and password. Use an existing secret, or create a new secret by specifying the Name and entering the Secret text.

      • Anonymous: No credentials required. This works for public Docker Hub images.

    • AWS ECR:

      • Access key: Specify the access key as plain text or as an encrypted secret, then specify the secret key by creating a new secret or selecting an existing one.

      • Anonymous: No credentials required. This works for public ECR repositories.

    • Custom:

      • Username and password: Specify the username and password. Use an existing secret, or create a new secret by specifying the Name and entering the Secret text.

      • Anonymous: No credentials required. This works for registries that need no authentication.

  9. Select Create to finalize.

Configure the upstream proxy in your registry

To configure the upstream proxy in your registry, perform the following steps:

  1. In Artifact Registry, select an existing Docker artifact.

  2. Navigate to the Configuration tab.

  3. Select Edit in the Upstream proxy section.

  4. Click + Add upstream proxy.

  5. Select the required proxy from the list.

  6. Select Apply.

  7. Click Update to finalize.

Upstream proxy caching

If an image is not found in your Harness registry, the upstream proxy fetches it from the remote registry and caches it.

Docker client setup

In your Harness Docker Artifact, select Set Up Client. The dialog gives you an identity token, then setup instructions for logging in, publishing, and pulling images with the Docker CLI.

Generate an identity token

An identity token serves as the password for authenticating with the registry.

  1. In your Docker Artifact, select Set Up Client.

  2. Select Generate Token.

  3. Select an Expiration for the token:

    • 30 Days

    • 90 Days

    • 180 Days

    • Custom

  4. Copy the token. You use it in the following steps in place of <IDENTITY_TOKEN>.

Token expiration

The identity token stops working after the expiration you select. Generate a new token and update your client configuration before the current token expires.

Configure the client

Replace the values in angle brackets with your own values.

1. Configure

Run the following command in your terminal to authenticate the Docker CLI with the registry:

At the prompts, enter the following:

  • Username: your Harness account email address.

  • Password: <IDENTITY_TOKEN>.

2. Publish an image

Tag the image to match the registry path, then push it:

3. Use the image

Make sure you are authenticated with the registry (see step 1), then pull the image by tag or by digest:

Setup verification

Confirm that your registry serves the image you published. To verify your setup, perform the following steps:

  1. On a host with no locally cached layers for the image you pushed, pull the image using the client command from the steps above.

  2. Confirm that the client pulled the image from your Harness registry address, which is shown in Set Up Client.

  3. In Harness, open your registry and confirm that the image and tag appear in the artifact list.

If a step fails, go to Troubleshooting to resolve common authentication and resolution issues before you retry.

Pipeline automation (optional)

Publishing from a pipeline gives you a repeatable release process. Run the publish step when you create a version tag, so each release maps to one image tag in the registry.

The following Run step shows the shape of a publish step. Replace <ACCOUNT_ID>, <REGISTRY_NAME>, and <IMAGE_NAME> with the values from the steps above. Store the identity token as a Harness secret, and do not write it into the pipeline YAML.

Troubleshooting

`docker login` fails with `401 Unauthorized` or `403 Forbidden`

Check that you entered your Harness account email address as the username, and the identity token, not your account password, as the password. If the token expired or was revoked, generate a new one and log in again.

`docker push` fails with `DENIED: requested access to the resource is denied` for an existing tag

Harness Artifacts enforces tag immutability for existing versions, depending on your registry configuration. Push a new tag, or delete the existing version only if your registry retention and lifecycle policies allow it.

`docker pull` fails with `manifest unknown` or `not found`

Check that the image name, tag or digest, and registry name in your pull command match the values you used when you pushed the image.

`docker pull` returns a cached image after a new push to the same tag

Docker caches image layers locally by tag. Remove the stale local image with docker rmi, or pull by digest instead of tag to always resolve the exact image you published.

Set Up Client does not show a push command for an upstream proxy registry

An upstream proxy registry is pull-only. Publish your images to a virtual (non-proxy) registry instead, or configure the upstream proxy to cache images pulled from the remote source.

Next steps

Last updated

Was this helpful?