Working with OCI Registries
1. Understanding OCI Registry Support
| Status | Detail |
|---|---|
| Stable since | Helm 3.8 (no env flag needed) |
| Protocol | OCI Distribution Spec — same as container images |
| Supported registries | GHCR, ECR, GCR, ACR, Harbor, Docker Hub, Artifactory, Quay |
| No index.yaml | Discovery via registry tag listing API |
2. Logging into Registry
Example: Login
helm registry login ghcr.io -u $GH_USER -p $GH_TOKEN
helm registry login --password-stdin ghcr.io -u $GH_USER <<< "$GH_TOKEN"3. Logging out of Registry
| Command | Effect |
|---|---|
helm registry logout ghcr.io | Remove credentials |
4. Pushing Chart to OCI
Example: Push packaged chart
helm package ./chart
helm push chart-1.4.2.tgz oci://ghcr.io/acme/charts
# Pushed: ghcr.io/acme/charts/chart:1.4.2Note: Repository segment in OCI ref is derived from chart name. The registry path is parent:
oci://ghcr.io/acme/charts + chart-1.4.2.tgz → ghcr.io/acme/charts/chart:1.4.2.5. Pulling Chart from OCI
Example: Pull tarball locally
helm pull oci://ghcr.io/acme/charts/chart --version 1.4.2
helm pull oci://ghcr.io/acme/charts/chart --version 1.4.2 --untar6. Installing from OCI
| Command | Notes |
|---|---|
helm install api oci://ghcr.io/acme/charts/api --version 1.4.2 | --version required for OCI |
helm upgrade --install ... | Idempotent |
7. Using OCI References
| Form | Resolves to |
|---|---|
oci://registry/path/chart | Chart at path; tag = --version |
oci://...:1.2.3 | Pinned version (in Chart.yaml dependency form) |
oci://...@sha256:abc | Digest-pinned (in OCI Chart.yaml deps) |
8. Listing OCI Chart Tags
Example: List versions via crane/oras
oras repo tags ghcr.io/acme/charts/api
crane ls ghcr.io/acme/charts/api
# helm has no built-in "list tags" — use OCI tooling9. Setting OCI Credentials
| Mechanism | Location |
|---|---|
helm registry login | Writes to ~/.config/helm/registry/config.json |
$DOCKER_CONFIG | Helm reads docker config if Helm config missing |
| Cloud auth helpers | ECR get-login-password, GCR gcloud auth print-access-token |
10. Using Docker Config
Example: Reuse docker credentials
export DOCKER_CONFIG=~/.docker
docker login ghcr.io
helm push chart-1.4.2.tgz oci://ghcr.io/acme/charts # uses docker creds11. Working with Private OCI Registries
| Concern | Solution |
|---|---|
| CI auth | Use short-lived tokens via helm registry login --password-stdin |
| In-cluster pull | Image pull secrets don't apply to charts; CI fetches charts before deploy |
| Mirroring | helm pull then helm push to internal registry |
| Air-gapped | Use oras copy to transfer between registries |