> For the complete documentation index, see [llms.txt](https://developer.harness.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developer.harness.io/artifact-registry/3.0/setup/helm-oci.md).

# Helm OCI

Helm OCI - push Helm charts to Harness Artifacts

Use a **Helm OCI** registry to push and pull Helm charts over the OCI protocol with the Helm CLI.

## What you will learn from this topic

By the end of this guide, you will know how to:

* Create a registry in Harness Artifacts.
* Publish a package to the registry.
* Install the package from the registry and confirm that it works.

## Before you begin

* Install the Helm CLI (`helm`) version 3.8 or later on your local machine. OCI support is enabled by default in these versions.
* Make sure you have access to a Harness account with permission to create registries and connectors.

## Create a Helm OCI Registry

To create a Helm OCI Registry:

1. In Artifact Registry, select **Registries**.
2. Select **+ Create Registry**.
3. Specify the **Registry name**.

{% hint style="info" %}
**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.
{% endhint %}

4. Optionally, add a **Description**.
5. Choose visibility between **Public** and **Private**. The default is *Private*.
6. Select **Helm OCI** as the **Registry type**.
7. Select **Save**.
8. Select **Create** to finalize.

## Upstream proxy configuration (optional)

An upstream proxy allows your registry to fetch Helm charts from AWS ECR or another OCI-compliant registry when they are not available locally.

### Create upstream proxy

To create an upstream proxy:

1. In Artifact Registry, select **Registries**.
2. Select 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 **Helm OCI** as the **Registry type**.
7. Select the **Source**: **AWS ECR** or **Custom**.
8. Specify the **Remote registry URL** for the OCI registry you want to proxy, for example `oci://registry-1.docker.io`.
9. Select the **Authentication method**.
   * **Access key and Secret key** (for **AWS ECR**): Specify the **Access key** as **Plain Text** or an encrypted value, then specify the **Secret key**. Use an existing secret, or create a new secret by specifying the **Name** and entering the **Secret text**.
   * **Username and password** (for **Custom**): 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 OCI registries that allow anonymous pulls.
10. Click **Create** to finalize.

### Configure the upstream proxy in your registry

To configure the upstream proxy in your registry:

1. In Artifact Registry, select an existing Helm OCI artifact.
2. Navigate to the **Configuration** tab.
3. Select **Edit** in the **Upstream proxy** section.
4. Select **+ Add upstream proxy**.
5. Select the required proxy from the list.
6. Select **Apply**.
7. Select **Update** to finalize.

{% hint style="info" %}
**Upstream proxy caching**

If a chart is not found in your Harness registry, the upstream proxy fetches it from the remote OCI registry and caches it.
{% endhint %}

## Helm OCI client setup

In your Helm OCI Artifact, select the registry, then select **Setup Client**. The dialog gives you an identity token and the login, push, and pull commands for your registry.

### Generate an identity token

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

1. In your Helm OCI Artifact, select **Setup 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>`.

{% hint style="info" %}
**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.
{% endhint %}

### Configure the client

In the code samples, replace the values in angle brackets with your own values.

**1. Authenticate the Helm CLI**

Log in to the registry:

```bash
helm registry login pkg.harness.io
```

When prompted, enter `<USERNAME>` for **Username** (your Harness account email) and `<IDENTITY_TOKEN>` for **Password**.

**2. Push a chart**

Package your chart, then push it to the registry:

```bash
helm push <CHART_TGZ_FILE> oci://pkg.harness.io/<ACCOUNT_ID>/<REGISTRY_NAME>
```

{% hint style="warning" %}
**The `oci://` prefix is required**

Add the `oci://` prefix to the repository URL in every push and pull command. Helm rejects the command with an invalid reference error if the prefix is missing.
{% endhint %}

**3. Pull a chart**

Pull a specific chart version from the registry by digest:

```bash
helm pull oci://pkg.harness.io/<ACCOUNT_ID>/<REGISTRY_NAME>/<IMAGE_NAME>@<DIGEST>
```

Replace `<IMAGE_NAME>` with the chart name and `<DIGEST>` with the chart's SHA256 digest, both shown in **Setup Client** and in your registry's package list.

## Setup verification

Confirm that your registry serves the chart you published. To verify your setup:

1. In a new directory with no cached charts or Helm repository index files, use the Helm CLI to pull the chart you published.
2. Confirm that the client downloaded the chart from your Harness registry address, which is shown in **Setup Client**.
3. In Harness, open your registry and confirm that the chart and version appear in the package list.

If a step fails, go to [Troubleshooting](#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 chart version in the registry.

The following Run step packages and pushes a chart. Store the identity token as a Harness secret, and do not write it into the pipeline YAML.

```yaml
- step:
    type: Run
    name: Publish chart
    identifier: publish_chart
    spec:
      shell: Sh
      envVariables:
        PACKAGE_VERSION: <+codebase.tag>
      command: |
        helm registry login pkg.harness.io --username <+secrets.getValue("ar_username")> --password <+secrets.getValue("ar_identity_token")>
        helm package <CHART_DIR> --version "$PACKAGE_VERSION"
        helm push <CHART_NAME>-"$PACKAGE_VERSION".tgz oci://pkg.harness.io/<ACCOUNT_ID>/<REGISTRY_NAME>
```

## Troubleshooting

<details>

<summary>`helm registry login`, `helm push`, or `helm pull` fails with `401 Unauthorized`</summary>

Check that the username and identity token match what you generated in **Setup Client**. If the token expired or was revoked, generate a new one and log in again.

</details>

<details>

<summary>`helm push` returns `409 Conflict`</summary>

Chart versions are immutable after publish. Bump the `version` field in `Chart.yaml`, repackage the chart, and push again.

</details>

<details>

<summary>`helm pull` fails with `not found` or `manifest unknown`</summary>

Check that the chart name, digest or tag, registry name, and account ID in the pull command match the values shown in **Setup Client** and the package list for the chart you published.

</details>

<details>

<summary>`helm push` or `helm pull` fails with an invalid reference error</summary>

Check that the repository URL starts with the `oci://` prefix. Helm rejects the command if the prefix is missing.

</details>

<details>

<summary>Setup Client does not show a push command for an upstream proxy registry</summary>

An upstream proxy registry is pull-only. To publish a chart, push it to a virtual Helm OCI registry instead, or configure the upstream proxy so pulled charts are cached automatically.

</details>

## Next steps

* To add a pipeline that publishes a new version for every release tag, go to [Harness CI](https://developer.harness.io/artifact-registry/3.0/platform-integrations/harness-ci.md).
* To control who can publish and consume packages in your registry, go to [RBAC and permissions](https://developer.harness.io/artifact-registry/3.0/reference/rbac-and-permissions.md).
* To set retention and lifecycle rules for old versions, go to [Lifecycle Management overview](https://developer.harness.io/artifact-registry/3.0/lifecycle-management/overview.md).

{% @harness-feedback/feedback %}
