> 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-http.md).

# Helm HTTP

Helm HTTP - host Helm charts in Harness Artifacts

Use a **Helm HTTP** registry to host, push, and pull Helm charts using the classic `helm repo add` or `helm pull` workflow. The registry works with the Helm CLI and `curl` for direct chart uploads.

## 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`) on your local machine.
* Install `curl`, which you use to push chart archives and provenance files to the registry.
* Make sure you have access to a Harness account with permission to create registries and connectors.

## Create a Helm HTTP Registry

To create a Helm HTTP 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 HTTP** as the **Registry type**.
7. Click **Save**.
8. Select **Create** to finalize.

## Configure an upstream proxy (optional)

An upstream proxy allows your registry to fetch Helm charts from external HTTP-based chart repositories when they are not available locally.

### Create upstream proxy

To create an upstream proxy:

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 **Helm HTTP** as the **Registry type**.
7. Select **Custom** as the **Source**, then specify the **Remote registry URL** (for example, `https://prometheus-community.github.io/helm-charts`).
8. Select the **Authentication method**.
   * **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 chart repositories.
9. Select **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 HTTP 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. Click **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 chart repository and caches it.
{% endhint %}

## Helm HTTP client setup

In your Helm HTTP Artifact, select the registry, then select **Setup Client**. The dialog gives you an identity token, then setup instructions for the Helm CLI and `curl`.

### Generate an identity token

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

1. In your Helm HTTP 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. Use the token in place of `<TOKEN>` in the following steps.

{% 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

Replace the values in angle brackets with your own values.

**1. Add the Helm repository**

Add your Harness registry as a Helm repository, authenticating with your username and the identity token:

```bash
helm repo add <REGISTRY_NAME> https://pkg.harness.io/pkg/<ACCOUNT_ID>/<REGISTRY_NAME>/helm-http --username <USERNAME> --password <TOKEN>
```

**2. Publish a chart**

Push a chart archive to the registry:

```bash
curl -u <USERNAME>:<TOKEN> -X PUT --data-binary @<ARTIFACT>-<VERSION>.tgz https://pkg.harness.io/pkg/<ACCOUNT_ID>/<REGISTRY_NAME>/files/<ARTIFACT>-<VERSION>.tgz
```

{% hint style="warning" %}
**Filename must match the chart metadata**

The `<ARTIFACT>` and `<VERSION>` in the `.tgz` filename must exactly match the `name` and `version` fields in the `Chart.yaml` packaged inside the archive. If they do not match, the push is rejected. For example, if `Chart.yaml` contains `name: my-chart` and `version: 1.2.3`, name the file `my-chart-1.2.3.tgz` and end the URL path with `/files/my-chart-1.2.3.tgz`.
{% endhint %}

Optionally, push a provenance file for the chart after the chart `.tgz` is pushed:

```bash
curl -u <USERNAME>:<TOKEN> -X PUT --data-binary @<ARTIFACT>-<VERSION>.tgz.prov https://pkg.harness.io/pkg/<ACCOUNT_ID>/<REGISTRY_NAME>/files/<ARTIFACT>-<VERSION>.tgz.prov
```

**3. Install a chart**

Update the local Helm repository cache:

```bash
helm repo update <REGISTRY_NAME>
```

Pull a specific chart version:

```bash
helm pull <REGISTRY_NAME>/<ARTIFACT> --version <VERSION>
```

## Setup verification

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

1. In a new directory with no existing Helm repository index or cached chart files, add your Harness registry as a Helm repository and update the local repository cache.
2. Pull the chart version you published, and confirm that Helm downloads it from your Harness registry address, 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 shows the shape of a publish step. Store the identity token as a Harness secret, and do not write it into the pipeline YAML.

```yaml
- step:
    type: Run
    name: Publish package
    identifier: publish_package
    spec:
      shell: Sh
      envVariables:
        CHART_VERSION: <+codebase.tag>
      command: |
        curl -u <USERNAME>:<TOKEN> -X PUT --data-binary @<ARTIFACT>-"$CHART_VERSION".tgz https://pkg.harness.io/pkg/<ACCOUNT_ID>/<REGISTRY_NAME>/files/<ARTIFACT>-"$CHART_VERSION".tgz
```

## Troubleshooting

<details>

<summary>`helm repo add` fails with `401 Unauthorized` or `403 Forbidden`</summary>

Check that the username and identity token in your `helm repo add` command match the ones shown in **Setup Client**. If the token has expired or was revoked, generate a new one and re-run `helm repo add` with the new token.

</details>

<details>

<summary>A chart push returns `409 Conflict`</summary>

Chart versions are immutable after publish. Choose a new SemVer version, or delete the existing version only if your registry retention and lifecycle policies allow it.

</details>

<details>

<summary>A chart push returns `400 Bad Request` for a filename mismatch</summary>

The `<ARTIFACT>` and `<VERSION>` in the `.tgz` filename must match the `name` and `version` fields in the `Chart.yaml` packaged inside the archive. Repackage the chart with matching values, or rename the file and update the URL path to match.

</details>

<details>

<summary>`helm pull` cannot find a chart, or resolves an old version</summary>

Run `helm repo update <REGISTRY_NAME>` to refresh the local index before you pull. Also check that the chart name and version in your `helm pull` command match the values you used when you published the chart.

</details>

<details>

<summary>Setup Client omits chart upload instructions</summary>

An upstream proxy registry is pull-only. Publish new charts to a virtual Helm HTTP registry instead, or configure the upstream proxy to cache charts from the remote chart repository on pull.

</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 %}
