---
url: /en/artifact/helm.md
description: >
  Guide for logging in, pushing, and pulling OCI-format Helm charts from the CNB
  Helm Artifact Registry, including artifact path naming rules and CI pipeline
  usage.
---
## Login to CNB Helm Artifact Registry

CNB Helm only supports Helm artifacts in OCI format.
It is recommended to use Helm v3.8.0 or above.
For details, please refer to the Helm documentation.

You can use CNB access token as login credentials.
For how to get `CNB_TOKEN`, please refer to
[Creating an Access Token](./intro.md#creating-an-access-token).
Login command:

```bash
helm registry login helm.cnbprod.alpha.qq.com -u cnb -p <YOUR_TOKEN>
```

> **Note**: The Helm registry only accepts Helm Charts (OCI format).
> Pushing other artifact types such as container images or Docker Model artifacts
> to the Helm registry address will be rejected. Ensure the push target matches
> the artifact type (see [Artifact Type Admission Restrictions](./intro.md#artifact-type-admission-restrictions)).

## Helm Artifact Path Rules

When publishing artifacts to a repository, two naming rules are supported:

1. **Same-name artifacts**: Artifact path matches repository path,
   e.g.: `helm.cnbprod.alpha.qq.com/${CNB_REPO_SLUG_LOWERCASE}`
2. **Different-name artifacts**: Repository path serves as namespace,
   artifact path = repository path/artifact name,
   e.g.: `helm.cnbprod.alpha.qq.com/${CNB_REPO_SLUG_LOWERCASE}/<ARTIFACT_NAME>`

Note: When using `helm push remote`, the chart name does not appear in the remote-url, but is read from the chart.

Therefore, for same-name artifacts,
the remote-url is `helm.cnbprod.alpha.qq.com/${CNB_GROUP_SLUG_LOWERCASE}`,
and for different-name artifacts,
the remote-url is `helm.cnbprod.alpha.qq.com/${CNB_REPO_SLUG_LOWERCASE}`.

## Pushing Artifacts

### Local Push

Same-name artifacts

```bash
helm package chart-path
helm push chartname-version.tgz oci://helm.cnbprod.alpha.qq.com/${CNB_GROUP_SLUG_LOWERCASE}
```

Different-name artifacts

```bash
helm package chart-path
helm push chartname-version.tgz oci://helm.cnbprod.alpha.qq.com/${CNB_REPO_SLUG_LOWERCASE}
```

### Push in Cloud Native Build

```yaml title=".cnb.yml"
main:
  push:
    - docker:
        image: alpine/helm
      stages:
        - name: helm login
          script: helm registry login -u ${CNB_TOKEN_USER_NAME} -p "${CNB_TOKEN}" ${CNB_HELM_REGISTRY}
        - name: helm package
          script: helm package ${YOUR_CHART_PATH}
        - name: helm push
          script: helm push chartname-version.tgz oci://${CNB_HELM_REGISTRY}/${CNB_GROUP_SLUG_LOWERCASE}
```

### Push in Workspaces

Same as local push. Replace `${YOUR_CHART_PATH}`, `${CNB_GROUP_SLUG_LOWERCASE}`, `${CNB_REPO_SLUG_LOWERCASE}` with actual values. See [Local Push](#local-push) above for details.

## Using Artifacts

### Pull from Local Command Line

```bash
helm pull oci://helm.cnbprod.alpha.qq.com/<ARTIFACT_PATH> --version <VERSION>

# ...
```

### Other Common Commands

#### View Helm Information

```bash
helm show all oci://helm.cnbprod.alpha.qq.com/<ARTIFACT_PATH> --version <VERSION>
```

#### Preview Manifest

```bash
helm template <RELEASE_NAME> oci://helm.cnbprod.alpha.qq.com/<ARTIFACT_PATH> --version <VERSION>
```

#### Install Helm Chart

```bash
helm install <RELEASE_NAME> oci://helm.cnbprod.alpha.qq.com/<ARTIFACT_PATH> --version <VERSION>
```

#### Upgrade Helm Chart

```bash
helm upgrade <RELEASE_NAME> oci://helm.cnbprod.alpha.qq.com/<ARTIFACT_PATH> --version <VERSION>
```

## Direct Download

In addition to OCI protocol commands such as `helm pull`, CNB also provides an HTTP direct download
endpoint for `.tgz` files. This endpoint returns the `.tgz` file stream as-is
(without a 302 redirect), making it suitable for downstream systems that only support raw tarballs.

### URL Format

The direct download URL format is:

```bash
# Same-name artifacts
https://helm.cnbprod.alpha.qq.com/charts/<NAMESPACE>/v/<VERSION>.tgz

# Different-name artifacts
https://helm.cnbprod.alpha.qq.com/charts/<NAMESPACE>/<CHART_NAME>/v/<VERSION>.tgz
```

Where `<NAMESPACE>` is the repository path (e.g., `${CNB_REPO_SLUG_LOWERCASE}`),
`<CHART_NAME>` is the chart name for different-name artifacts,
and `<VERSION>` is the artifact version.

### Authentication and Example

* Public repositories: Access the URL directly without authentication.
* Private repositories: Use HTTP Basic Authentication with username `cnb`
  and the [access token](./intro.md#creating-an-access-token) as the password.

```bash
# Download a different-name artifact from a private repository
curl -u cnb:${CNB_TOKEN} -fOJ \
  "https://helm.cnbprod.alpha.qq.com/charts/${CNB_REPO_SLUG_LOWERCASE}/mychart/v/0.6.0.tgz"
```

The endpoint returns the `.tgz` file stream (HTTP 200) without redirects.
The `Content-Disposition` response header carries the normalized download filename
`{CHART_NAME}-{VERSION}.tgz`.

## More Information

For more Helm usage, please refer to the [Helm official documentation](https://helm.sh/docs/).