Using Helm OCI Registries to Store and Deploy Charts

Problem: Chart distribution tied to separate repositories

Many teams keep Helm charts in a dedicated chart museum or Git‑based repo while container images live in an OCI registry. This split means maintaining two sets of access policies, retention rules, and scanners, and it adds a step to pull charts before a release can be installed.

Thesis: Helm’s built‑in OCI support lets you treat charts as ordinary OCI artifacts, unifying storage and simplifying governance.

Starting with Helm 3.8, the helm push and helm pull commands understand the oci:// scheme. A chart is packaged as a tarball, referenced by an OCI manifest, and stored alongside your container images. You can then apply the same retention, vulnerability scanning, and RBAC policies you already use for images.

How to enable and verify OCI chart storage

1. Check Helm version – run helm version and confirm the output shows v3.8.0 or higher.
2. Start a local OCI‑capable registry (for testing) –

   docker run -d -p 5000:5000 --name reg registry:2

   This pulls the official registry image and exposes it on localhost:5000.
3. Log in to the registry with Helm –

   helm registry login localhost:5000

   You will be prompted for a username and password; the default registry image accepts any credentials (e.g., test/test).

Worked example: push, pull, and install a chart from an OCI registry

We’ll create a simple chart, push it to the local registry, pull it in a different directory, and install it.

1. Create a chart

helm create demo-chart
# This creates a directory demo-chart/ with Chart.yaml, values.yaml, templates/, etc.

2. Push the chart

helm push demo-chart oci://localhost:5000/demo-chart

If successful, Helm prints something like Pushed: oci://localhost:5000/demo-chart:0.1.0. The chart version is taken from Chart.yaml. Pushing an existing version without incrementing will overwrite the artifact; to avoid accidental loss, always bump the version (e.g., edit Chart.yaml before pushing).

3. Pull the chart in a clean workspace

mkdir -p /tmp/pull-demo && cd /tmp/pull-demo
helm pull oci://localhost:5000/demo-chart --version 0.1.0 --untar

The --untar flag extracts the chart tarball directly into the current directory, leaving a demo-chart/ folder.

4. Verify the pulled chart matches the source

Run a diff on the Chart.yaml files:

diff -u ~/demo-chart/Chart.yaml /tmp/pull-demo/demo-chart/Chart.yaml

No output indicates the files are identical.

5. Install the chart directly from the OCI registry

You can skip the pull step and install in one command:

helm upgrade --install my-release oci://localhost:5000/demo-chart --version 0.1.0 -f my-values.yaml

Helm will fetch the chart from the registry, render templates with my-values.yaml, and create the release.

Trade‑offs and limitations

• Registry compatibility – Not all container registries implement the OCI Distributions spec for artifacts. Older registries or those with artifact storage disabled will return an "unsupported media type" error when you run helm push. Verify support by checking the registry’s documentation or attempting a push of a small test chart.
• Chart dependencies – Helm OCI does not yet resolve dependencies that themselves live in OCI registries. Subcharts must be bundled locally (using helm dependency update) or referenced via traditional chart repositories until this feature matures.
• Version management – Because the chart is stored as an OCI artifact, pushing the same version overwrites the existing artifact. Adopt a strict version‑bump policy (e.g., follow SemVer) and consider enabling immutability features in your registry if available.

Practical way to check the result in CI

Add a verification stage after the push step:

1. Pull the chart with --untar into a temporary directory.
2. Run helm lint on the pulled chart to ensure it is still well‑formed.
3. Optionally, run a dry‑run install: helm upgrade --install --dry-run --wait test oci://// --version .
4. If any step fails, the pipeline should halt and alert the team.

Actionable closing

If you are already using Helm 3.8 or newer and your container registry supports OCI artifacts, start by pushing a single chart to test the flow. Use the verification steps above to confirm integrity, then extend the pattern to your CI pipeline so that chart releases travel alongside your container images under a single set of policies. This reduces operational overhead and brings chart distribution in line with the rest of your cloud‑native workflow.