Skip to content
Tutorials Center
My learning

Topics

Lesson 27 of 38 ยท Repositories and OCI

OCI Registries: Push and Pull Helm Charts

Store Helm charts in OCI registries with helm registry login, helm push and oci:// install, learn reference rules and tag mapping, with a reference-parser stand-in.

Container images live in registries such as Docker Hub, GitHub Container Registry, Amazon ECR, Google Artifact Registry and Azure Container Registry. These registries follow the OCI (Open Container Initiative) standard, and the standard is general enough to store other artifacts too. Helm 3.8 made OCI support stable: you can push charts to the registry you already run, with the same authentication, access control and replication as your images.

Why use OCI for charts

  • One system. No separate chart server and no index.yaml to regenerate.
  • Existing security. Registry accounts, tokens and permissions apply.
  • Content addressing. Charts are identified by a digest (sha256:...), which makes them tamper-evident.
  • Fewer moving parts in CI. The same login serves docker push and helm push.

The price is that there is no repository search: helm search repo does not work against OCI, because a registry has no index of charts. You use known names (or Artifact Hub, covered later).

Logging in

Terminal
echo "$REGISTRY_TOKEN" | helm registry login ghcr.io --username my-user --password-stdin

Helm reuses credentials from Docker's config when they exist. helm registry logout ghcr.io removes them.

Pushing a chart

First package, then push to a path under the registry host. The path must be a repository prefix; Helm appends the chart name and uses the chart version as the tag:

Terminal
helm package ./webapp                       # webapp-0.3.0.tgz
helm push webapp-0.3.0.tgz oci://ghcr.io/my-org/charts
# Pushed: ghcr.io/my-org/charts/webapp:0.3.0
# Digest: sha256:4e6f...

Notice what is stored: the chart name webapp becomes the last part of the repository and 0.3.0 becomes the tag. SemVer allows a + in versions (1.0.0+build5), but OCI tags cannot contain +, so Helm replaces it with _.

Pulling and installing

You do not repo add an OCI location. Use the full reference:

Terminal
helm pull oci://ghcr.io/my-org/charts/webapp --version 0.3.0 --untar
helm show values oci://ghcr.io/my-org/charts/webapp --version 0.3.0
helm install shop oci://ghcr.io/my-org/charts/webapp --version 0.3.0
helm upgrade shop oci://ghcr.io/my-org/charts/webapp --version 0.3.1

Two details: the reference includes the chart name (.../charts/webapp), whereas push takes only the prefix (.../charts), and the version goes in --version (or @sha256:... to pin the digest).

To pin to an immutable digest:

Terminal
helm install shop oci://ghcr.io/my-org/charts/webapp@sha256:4e6f...

OCI charts as dependencies

In Chart.yaml, set repository to the registry prefix, with no chart name:

YAML
dependencies:
  - name: webapp-common
    version: "1.2.0"
    repository: "oci://ghcr.io/my-org/charts"

Helm builds the reference as repository/name. This is the most common source of mistakes: writing the chart name in both places.

A stand-in for reference rules

The stand-in below parses references and shows how Helm composes them for push and for dependencies. It is a model of the rules, not Helm's code.

Python Stand-in: compose and parse OCI chart references

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Registry-specific notes

Registry Tip
Docker Hub Use oci://registry-1.docker.io/<user> as the prefix
GitHub (ghcr.io) Package visibility is separate from repository visibility; make it public if consumers have no token
Amazon ECR Create the repository named exactly like the chart first; log in with aws ecr get-login-password
Azure ACR az acr login then helm push; enable OCI artifact support on older SKUs
Harbor, Artifactory Support OCI charts; check the project allows Helm artifacts

Because the chart is stored as layers with media types such as application/vnd.cncf.helm.chart.content.v1.tar+gzip, some registries show it as a "Helm chart" and others as unknown. Both work.

Migrating from classic repositories

You can run both in parallel: publish each new version to OCI and keep the old repository read-only. Update consumers' Chart.yaml dependency repository values one at a time and rebuild lock files with helm dependency update. Do not delete the old index while any Chart.lock still references it.

Troubleshooting

  • "unauthorized": log in again; tokens need write:packages (GitHub) or the registry's push role.
  • "not found" on pull: you included the prefix only, or forgot the chart name.
  • Tag already exists and registry is immutable: bump the chart version.
  • Plain-HTTP local registry: add --plain-http (for example when testing with a local registry:2 container).
Python Stand-in: pick the tag, handle the plus sign

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Check your understanding

Quick check ยท 3 questions

of 3 answered You scored / 3 ยท perfect!

  1. 1. What does helm push webapp-0.3.0.tgz oci://ghcr.io/my-org/charts store?

    The chart name is appended to the prefix and the chart version becomes the tag.
  2. 2. Which command does NOT work with OCI registries?

    A registry has no chart index, so helm search repo cannot list OCI charts.
  3. 3. In Chart.yaml, what should the repository be for an OCI dependency?

    Helm appends the dependency name itself.

Summary

  • OCI registries store charts with the same tools as container images; use helm registry login, helm push, oci:// references.
  • Push takes a prefix; pull and install take the full reference including the chart name.
  • The chart version becomes the tag (+ becomes _); pin to a digest for strict reproducibility.
  • There is no helm search repo for OCI.

Next: Helm Plugins and Artifact Hub