Hands-on with Helm: migrating and packaging charts to OCI registries

Helm has been the de facto package manager for Kubernetes for years. But the way we distribute charts is changing: the community is moving from index.yaml-style chart repositories (the old “charts.example.com”) toward storing charts as OCI artifacts in container registries. That shift affects how you package, sign, host, and deploy charts — and it’s a great opportunity to simplify CI/CD and reuse the same registry tooling you already have for container images. In this hands-on guide I’ll explain why the change matters, show the practical Helm commands and a simple migration workflow, and walk through a few gotchas and best practices to keep your releases sane. (helm.sh)

Why OCI for Helm charts?

A few clear reasons have driven the move:

• Single API and tooling: container registries implement a common OCI distribution API, so the same authentication and lifecycle tools you use for images can also be used for charts. That simplifies pipelines and governance. (helm.sh)
• Scalability and security: registries are battle-tested for large binary storage, access control, and scanning integrations. Many orgs already trust them for images, so charts piggyback on that same infrastructure. (helm.sh)
• Vendor momentum: major chart providers and cloud registries have been transitioning to OCI-first delivery (for example Bitnami and several cloud registries have announced or implemented this move). That means consumers will increasingly expect OCI distribution. (github.com)

Helm’s OCI story became production-ready when OCI support graduated out of experimental mode in Helm 3.8.0; that’s the baseline you should target for the features and behaviors below. (helm.sh)

Quick primer: core Helm OCI commands

Workflow in OCI mode is straightforward and mirrors what you already do for images.

• Package a chart:

  helm package ./mychart
  # creates mychart-0.1.0.tgz
  

• Log in to an OCI registry (example with Docker Hub / GHCR / ACR):

  # Docker login for registries that accept docker credentials
  docker login ghcr.io
  # or with helm's registry commands
  helm registry login ghcr.io -u USER --password-stdin
  

• Push the packaged chart as an OCI artifact:

  helm push mychart-0.1.0.tgz oci://ghcr.io/myorg/helm-charts
  # Pushed: ghcr.io/myorg/helm-charts/mychart:0.1.0
  

• Install directly from the registry:

  helm install myrelease oci://ghcr.io/myorg/helm-charts/mychart --version 0.1.0
  

• Pull a chart locally:

  helm pull oci://ghcr.io/myorg/helm-charts/mychart --version 0.1.0
  

A few practical notes from the Helm docs: the oci:// prefix is required for registry references; chart names map to the repository basename and chart versions map to the OCI tag. Some registries require you to create the repository/namespace ahead of time. (helm.sh)

A simple migration recipe

If you have existing chart archives or an index.yaml-based repo, the basic migration steps look like this:

1. Ensure your toolchain uses Helm >= 3.8.
2. Build the packaged chart:

   helm package ./mychart
   

3. Authenticate to your chosen registry (Docker Hub, GHCR, ACR, Artifact Registry, Harbor, etc.).
4. Push the chart:

   helm push mychart-0.1.0.tgz oci://$REGISTRY/$NAMESPACE/helm-charts
   

5. Update deployment pipelines / GitOps manifests to point to the OCI reference (e.g. oci://ghcr.io/myorg/helm-charts/mychart –version 0.1.0), or use helm pull/install as above.

If you need to migrate many charts, a small script that iterates through tgz files and does helm push is usually sufficient. For repositories that still expect index.yaml, you can keep an index façade for backward compatibility during the transition; some maintainers publish an index as well as OCI artifacts for this reason. Bitnami, for instance, announced an OCI-first default while keeping backward compatibility mechanisms during the transition. (community.broadcom.com)

Real-world example: several projects (including secureCodeBox and many cloud providers) have published migration guides that show simple helm package + helm push flows, and explain how existing chart consumers can switch to the OCI reference. If you run into registry quirks (e.g., namespace creation or permissions), consult the provider docs — the behavior varies. (securecodebox.io)

Provenance and signing: trust matters

One common worry is “how do I verify chart provenance in OCI?” Helm’s traditional GPG-based provenance files (.prov) still exist, but the community is also adopting Sigstore tooling (cosign, Rekor) to sign and record tamper-evident attestations. The community-maintained helm-sigstore plugin lets you upload and verify charts against Sigstore’s transparency logs, integrating chart signing into modern supply-chain workflows. Additionally, policy controllers can enforce signature requirements at admission time. If you need strict attestations in your cluster, pair signed OCI charts with a policy controller that validates signatures before admission. (github.com)

CI/CD notes: where to plug this in

• Packaging step: helm package in the build job.
• Upload step: helm registry login + helm push to your registry (or use the registry’s CLI if required).
• Release metadata: push semantically versioned tags; the chart version maps to the OCI tag so your release semantics remain consistent.
• Signing: run helm-sigstore / cosign in the pipeline to generate and publish signatures and provenance.
• Consumption: update GitOps/Helm commands to reference oci:// URIs. Note that helm repo add and helm search will not discover OCI registries the same way; you’ll often install/upgrade by oci:// reference or use a separate index for discoverability if necessary. (helm.sh)

Common gotchas and caveats

• Helm search limitations: OCI-based registries aren’t discoverable via helm search the same way traditional chart repos are. You’ll need to rely on registry listings, an index facade, or your own catalog/index service for discovery. (helm.sh)
• Registry differences: some registries require creating repositories ahead of push or have slightly different auth flows (Azure ACR, GHCR, Docker Hub); read the registry docs. Microsoft has been deprecating legacy Helm v2-style repository features and steering users toward Helm 3 + OCI artifacts, so watch provider timelines. (github.com)
• Plugin collisions: historically, community plugins like the helm-push plugin used to manage pushes to ChartMuseum; Helm’s built-in helm push can conflict with those plugins. The chartmuseum plugin was renamed to avoid that confusion (e.g., cm-push). Expect to tidy up your local plugins if you migrate. (helm.sh)
• Index.yaml expectations: some consumers (scripts, old tooling, or users) still rely on index.yaml. You can generate or host an index for compatibility, but be aware that indexes and OCI artifacts are different primitives. Bitnami and others kept index compatibility during their transition to minimize disruption. (community.broadcom.com)

Best practices for packaging and releases

• Semver strictly: since chart versions map to OCI tags, follow semantic versioning carefully to avoid tag collisions or accidental overwrites. (helm.sh)
• CI immutability: ensure CI publishes immutable tags (don’t reuse tags) and that your registry enforces immutability if you need strict guarantees.
• Sign everything: integrate signing (sigstore / cosign) into your pipeline and publish provenance so consumers and admission controllers can validate. (github.com)
• Document the registry URI: make the OCI reference the canonical source in charts’ README and your deployment docs. Include instructions for helm registry login and how to pull/install from the OCI URI.
• Monitor access policies: reuse your image registry RBAC, scanning, and lifecycle policies for charts so they inherit the same security posture as container images.

Real-world signals

The migration trend is more than theoretical. Bitnami announced moving charts to default to OCI distribution and cloud vendors (including Azure) have been removing legacy Helm repository support in favor of OCI artifacts. Open-source projects and smaller vendors are following suit because registry infrastructure scales better and reduces operational blur between image and chart management. If you manage enterprise or public charts, this is a good time to evaluate migration windows and compatibility layers for your users. (github.com)

Final thoughts

Switching to OCI for Helm charts is largely evolutionary, not revolutionary: the packaging steps remain familiar (helm package) while distribution benefits from the durability, access controls, and ecosystem of container registries. If you standardize on OCI artifacts, you can consolidate artifact storage, reuse the same scanning and RBAC tooling, and embrace modern signing and verification workflows. The practical steps are simple — package, login, push — but the real value comes from aligning chart delivery with the rest of your supply chain tooling. (helm.sh)

References (selected)

• Helm: Using OCI-based registries and command reference. (helm.sh)
• Helm HIP and OCI rationale. (helm.sh)
• Microsoft / Azure Container Registry deprecation notes and guidance to use OCI artifacts. (github.com)
• Bitnami and other chart providers discussing or implementing OCI-first distribution. (github.com)
• Sigstore helm-sigstore plugin and Sigstore docs for signing charts. (github.com)