In Chapters 1-6, you built Helm charts locally: templating logic, dependency composition, hooks, and validation. These charts work perfectly in your development environment. But when you need to share charts across teams, use them in production, or compose them as dependencies in other charts, storing them as directories on your laptop doesn't scale.
Helm solved this by adopting OCI (Open Container Initiative) standards. The same registry that stores your Docker images—Docker Hub, Amazon ECR, Azure Container Registry—now stores your Helm charts. This unifies distribution: one registry for both container images AND charts, one authentication mechanism, one versioning strategy.
This chapter teaches you how to package charts into distributable artifacts, authenticate with registries, push and pull charts, consume charts from OCI URLs, and implement a chart versioning strategy aligned with semantic versioning. By the end, you'll publish your AI agent's Helm chart to a shared registry where teammates and production systems can discover and install it.
This chapter covers the complete workflow for distributing Helm charts via OCI-compliant registries.
Before starting this chapter, you should have:
Before you can push a chart to a registry, understand what OCI is and why Helm moved from Helm repositories (custom format) to OCI.
Before OCI adoption (Helm 2-early Helm 3):
Teams maintained two completely different distribution systems with different credentials, different APIs, different versioning semantics.
After OCI adoption (Helm 3.7+):
One registry. One authentication model. One API.
OCI (Open Container Initiative) is a standardized format for packaging and distributing artifacts. Originally designed for container images, OCI is now a general-purpose artifact format that can store anything: images, charts, software bills of materials (SBOMs), vulnerability scan results.
An OCI registry is any system that follows the OCI Distribution Spec:
A Helm chart stored in OCI format is just an artifact in these registries, no different from a Docker image.
When you helm package a chart, Helm:
A Helm chart in a registry looks like this:
It's identical in structure to a Docker image reference:
Same registry. Same tagging system. Same authentication.
Before pushing to a registry, you must package your chart into a .tgz archive.
Start with an existing chart (or the example from Lesson 1):
Output:
The filename comes from Chart.yaml:
If you change version in Chart.yaml, helm package creates a new file:
Each version is a separate artifact. This is how semantic versioning works: 1.2.3 represents major.minor.patch. When you fix a bug, bump patch (1.2.4). When you add backwards-compatible features, bump minor (1.3.0). When you make breaking changes, bump major (2.0.0).
When you push a chart to an OCI registry, you reference it using oci:// URLs.
Breaking this down:
Public chart on Docker Hub:
Private chart on Amazon ECR:
Local registry for development:
Before OCI, Helm used HTTP repository URLs (still supported):
The OCI approach is simpler: no separate repository infrastructure, same registry as your images.
Before you push or pull charts from a private registry, authenticate using helm registry login.
Output:
If you've already logged in with the Docker CLI:
For Amazon ECR, Azure ACR, or other private registries:
Output:
Helm stores credentials in ~/.docker/config.json (same as Docker CLI). Each registry gets its own credential entry.
Once authenticated, push your packaged chart to an OCI registry using helm push.
Output:
Output:
When you push, Helm separates chart name from version:
The version goes into the tag (after the colon), not the image name. This matches Docker convention:
You've learned the foundation of OCI-based chart distribution.
Quick Reference:
Self-Check Questions:
Why did Helm adopt OCI standards instead of maintaining custom Helm repositories?
What file determines the name of the .tgz archive created by helm package?
How does an OCI chart URL differ from a Docker image URL?
If you can't answer these, review Concepts 1-3 before continuing.
Download charts from OCI registries using helm pull.
Output:
Output:
Output:
You've mastered the publish-and-consume workflow for OCI registries.
Quick Reference:
Self-Check Questions:
Where does Helm store registry credentials after helm registry login?
What happens if you push a chart version that already exists in the registry?
Can you install a chart directly from an OCI URL without pulling first?
If you can't answer these, review Concepts 4-6 before continuing.
Helm charts follow semantic versioning (semver): MAJOR.MINOR.PATCH.
Scenario 1: Fix indentation bug in service template
Scenario 2: Add optional monitoring sideca (optional feature)
Scenario 3: Add required field in values.yaml (for security context)
Output:
Instead of downloading then installing, install directly from OCI URLs.
Output:
Output:
In Lesson 4 (Chart Dependencies), you used HTTP URLs to reference external charts. You can also reference them via OCI.
Output:
You can mix HTTP (traditional Helm repos) and OCI in the same chart:
Output:
You've learned production-grade versioning and chart composition strategies.
Quick Reference:
Self-Check Questions:
When should you bump the MAJOR version of a Helm chart?
Can you install a chart from an OCI registry without downloading it first?
What's the advantage of using OCI URLs in Chart.yaml dependencies instead of HTTP repository URLs?
If you can't answer these, review Concepts 7-9 before continuing.
Before starting the exercises, avoid these frequent errors:
Wrong:
Right:
Why: Private registries (and even public pushes) require authentication. Always helm registry login before pushing.
Wrong:
Right:
Why: The version in Chart.yaml determines both the .tgz filename and the registry tag. Keep them synchronized.
Wrong:
Right:
Why: Helm charts are stored in OCI registries but aren't Docker images. Use helm pull, not docker pull.
Wrong:
Right:
Why: helm push expects a repository path (directory), while helm pull and helm install expect a full artifact reference (chart name + version).
Wrong:
Right:
Why: Reusing versions creates ambiguity. Consumers can't tell if they have the buggy or fixed version. Follow semantic versioning: always bump version for changes.
Create a simple chart and package it:
Output:
For learning, use a public registry to avoid authentication complexity:
Go to https://hub.docker.com
Click "Sign up"
Create account: username, email, password
Verify email
On your local machine:
Output:
Using the packaged chart and Docker Hub credentials:
Output:
Download your published chart:
Output:
Deploy using the OCI chart reference without downloading first:
Output:
Modify your chart and publish version 1.1.0:
Output:
If you don't have access to Docker Hub or prefer to keep charts private during development, you can run a local OCI registry:
Output:
Step 1: Initial Request
Ask AI to explain the differences between pushing Helm charts to OCI registries versus traditional Helm repositories:
Prompt: "Explain the key differences between distributing Helm charts via OCI registries (like Docker Hub) versus traditional Helm repositories. Why did Helm move to OCI standards?"
Step 2: Critical Evaluation
Review AI's response. Ask yourself:
Step 3: Constraint Teaching
If AI missed important details, refine your question:
"Also explain how authentication works—what credentials do I need to push to Docker Hub for both images and Helm charts?"
Step 4: Refinement
Ask AI to validate how you'd push a chart to a private Amazon ECR registry:
"Walk me through the steps to push a Helm chart to a private ECR repository in AWS. What commands do I run, and what credentials do I need?"
Step 5: Final Check
Compare what you learned from AI to the concepts in this chapter:
You built a helm-chart skill in Chapter
Ask yourself:
If you found gaps: