Skip to main content
Until now we have used Git as the single source of truth for declarative manifests. This lesson shows how to store and distribute Helm charts as OCI artifacts using an OCI-compatible registry (for example, Docker Hub). Many registries implement the OCI Distribution Specification — Docker Hub can host container images and other OCI artifacts such as Helm charts, SBOMs, digital signatures, and vulnerability reports. Below is a compact, corrected walkthrough that packages a Helm chart named highway-chart, pushes it to Docker Hub’s OCI registry, and then pulls and installs it from the registry. The examples use the Docker Hub username siddharth67; replace it with your own when running commands.
Ensure you are using Helm 3.x with OCI support. Helm 3.8+ includes built-in OCI support; some older 3.x releases required experimental flags or community plugins. Also confirm your Docker Hub credentials (password or Personal Access Token) before running helm registry login.

​
Prerequisites

  • Helm 3.x installed and on your PATH.
  • A Docker Hub account (or another OCI registry) and credentials.
  • kubectl configured for your target cluster if you plan to install the chart.

​
1) Create and package a Helm chart

If you do not already have a chart, scaffold one: 
helm create demo
Package a chart into a tarball: 
helm package demo
# Example output:
# Successfully packaged chart and saved it to: /path/to/demo-0.1.0.tgz
Using the example chart for this lesson (located at manifests/helm/highway-chart): 
cd manifests/helm/highway-chart
helm package .
# Successfully packaged chart and saved it to: /home/demos/manifests/helm/highway-chart/highway-chart-0.1.0.tgz

​
2) Authenticate to Docker Hub (OCI registry)

Log in to Docker Hub using Helm’s registry login. Replace siddharth67 with your Docker Hub username: 
helm registry login registry-1.docker.io -u siddharth67
# Password: <enter password or token>
# Login Succeeded
Docker Hub may require a Personal Access Token instead of your account password depending on your account settings. If authentication fails, create a token in Docker Hub and use it as the password.

​
3) Push the packaged chart to Docker Hub (OCI)

When pushing a Helm chart as an OCI artifact, push it under your Docker Hub namespace. The destination format is oci://registry-1.docker.io/<your-username>. Example: 
helm push highway-chart-0.1.0.tgz oci://registry-1.docker.io/siddharth67
# Pushed: registry-1.docker.io/siddharth67/highway-chart:0.1.0
# Digest: sha256:<digest-value>
Important: pushing to the oci://registry-1.docker.io/docker namespace will fail with 401 Unauthorized unless docker is your namespace. Always use your own username or organization namespace.

​
4) Pull the chart from Docker Hub (OCI)

You can pull the chart tarball from the OCI registry with helm pull. Always include the chart name and version to avoid Helm attempting to list tags (which may require additional authentication): 
helm pull oci://registry-1.docker.io/siddharth67/highway-chart --version 0.1.0
# Pulled: registry-1.docker.io/siddharth67/highway-chart:0.1.0
# Digest: sha256:<digest-value>

​
5) Install the chart directly from the OCI registry

Helm can install charts directly from an OCI URL without first pulling a tarball. Example below creates a namespace and installs the chart using an explicit values file: 
kubectl create namespace oci-demo

helm install oci-demo-release oci://registry-1.docker.io/siddharth67/highway-chart \
  --version 0.1.0 \
  --values ../cgoa-demos/manifests/helm/highway-chart/values.yml \
  -n oci-demo
Example successful output: 
Pulled: registry-1.docker.io/siddharth67/highway-chart:0.1.0
Digest: sha256:<digest-value>
NAME: oci-demo-release
LAST DEPLOYED: <timestamp>
NAMESPACE: oci-demo
STATUS: deployed
REVISION: 1
TEST SUITE: None
Verify the release resources: 
kubectl -n oci-demo get all
# Example output:
# NAME                                                READY   STATUS    RESTARTS   AGE
# pod/highway-animation-c5cccf6b-nrj15                1/1     Running   0          9s
# ...

​
6) Using OCI artifacts with GitOps tools

Many GitOps tools can use OCI registries as application sources for Helm charts. Example Argo CD Application (reference): 
apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: my-custom-image
  namespace: argocd
spec:
  project: default
  source:
    path: .
    repoURL: oci://registry-1.docker.io/some-user/my-custom-image
    targetRevision: 1.16.1
  destination:
    server: "https://kubernetes.default.svc"
    namespace: my-namespace
If the OCI registry is private, provide credentials to Argo CD via a Kubernetes Secret and configure Argo CD to use it. The same principle applies to Flux CD: create an OCIRepository and supply credentials when required. Example Flux OCIRepository: 
---
apiVersion: source.toolkit.fluxcd.io/v1
kind: OCIRepository
metadata:
  name: podinfo
  namespace: default
spec:
  interval: 5m0s
  url: oci://ghcr.io/stefanprodan/manifests/podinfo
  ref:
    tag: latest

​
7) Quick reference — common Helm OCI commands

TaskCommand / Example
Package a charthelm package ./path-to-chart
Login to registryhelm registry login registry-1.docker.io -u <username>
Push chart to OCIhelm push chart-0.1.0.tgz oci://registry-1.docker.io/<username>
Pull chart from OCIhelm pull oci://registry-1.docker.io/<username>/chart --version 0.1.0
Install from OCIhelm install release oci://registry-1.docker.io/<username>/chart --version 0.1.0 -n <ns>

​
8) Summary and best practices

  • Use helm package to create chart tarballs and helm push to upload them as OCI artifacts.
  • Authenticate with helm registry login. For Docker Hub, prefer a Personal Access Token if your account requires it.
  • Always push to your own Docker Hub namespace (for example, oci://registry-1.docker.io/<your-username>).
  • Install charts directly from OCI with helm install to avoid manual tarball handling.
  • For GitOps automation, configure Argo CD or Flux to read from OCI registries and provide registry credentials via Kubernetes Secrets when registries are private.
  • Automate credential rotation and secret management for production pipelines to reduce risk.
Resources and references: That’s all — with these steps you can package Helm charts as OCI artifacts, publish them to registries like Docker Hub, and consume them manually or through GitOps workflows.

Watch Video

Practice Lab