Home / Blogs / Orchestration / Helm Charts / OCI Repositories

OCI Repositories

Chartmuseum OCI Registry Integration Pushing Charts to OCI

A comprehensive guide to OCI repositories for Helm covering chartmuseum, OCI registry integration, pushing charts to OCI, and best practices for modern Helm chart distribution.

Chartmuseum OCI Registry Pushing Charts
What are OCI Repositories?

OCI (Open Container Initiative) repositories are a modern way to store and distribute Helm charts using the same infrastructure as container images. Helm v3.7+ supports OCI registries as a native chart distribution method.

OCI repositories provide several advantages over traditional Helm repositories:

  • Unified Infrastructure: Use the same registry for images and charts
  • Native Authentication: Use docker/registry authentication
  • Better Security: Built-in signing and verification
  • Simplified Management: Single set of tools and policies
  • Improved GitOps: Better integration with GitOps workflows
Key Concept: OCI repositories treat Helm charts as OCI artifacts, storing them alongside container images in the same registry. This is the future of Helm chart distribution.
OCI vs Traditional Repositories
Feature Traditional Helm Repo OCI Registry
Protocol HTTP/HTTPS OCI (Registry API)
Storage index.yaml + tgz files OCI artifacts
Authentication Basic Auth docker login (token-based)
Signing Provenance files Built-in OCI signing
Versioning Semver in index.yaml OCI tags
Dependencies Chart.yaml Chart.yaml + OCI URLs
Compatibility Helm v2/v3 Helm v3.7+
CI/CD Integration Good Excellent
Chartmuseum: Traditional Helm Repository Server

Chartmuseum is an open-source Helm Chart Repository server that provides a simple way to host and manage Helm charts. It supports both traditional repository mode and OCI registry mode.

# Install Chartmuseum using Helm helm repo add chartmuseum https://chartmuseum.github.io/charts helm repo update helm install chartmuseum chartmuseum/chartmuseum \ --namespace chartmuseum \ --create-namespace \ --set env.open.DISABLE_API=false \ --set env.open.ALLOW_OVERWRITE=true \ --set persistence.enabled=true \ --set persistence.size=10Gi # Install Chartmuseum with OCI support helm install chartmuseum chartmuseum/chartmuseum \ --namespace chartmuseum \ --set env.open.DISABLE_API=false \ --set env.open.ALLOW_OVERWRITE=true \ --set env.open.OCI_ENABLED=true \ --set env.open.OCI_STORAGE=oci://myregistry.azurecr.io/chartmuseum # Access Chartmuseum UI kubectl port-forward -n chartmuseum svc/chartmuseum 8080:8080 # Package and upload chart helm package ./my-chart curl --data-binary "@my-chart-1.0.0.tgz" \ http://localhost:8080/api/charts # List charts in Chartmuseum curl http://localhost:8080/api/charts # Download chart from Chartmuseum helm pull http://localhost:8080/charts/my-chart-1.0.0.tgz # Use Chartmuseum as Helm repo helm repo add local http://localhost:8080 helm repo update helm search repo local
Chartmuseum Best Practices:
  • Enable persistence for production deployments
  • Configure authentication for private repositories
  • Enable OCI mode for modern deployments
  • Set up regular backups
  • Monitor storage usage
OCI Registry Integration

AWS ECR

# Login to AWS ECR aws ecr get-login-password --region us-east-1 | \ helm registry login --username AWS --password-stdin my-account.dkr.ecr.us-east-1.amazonaws.com # Create ECR repository aws ecr create-repository --repository-name helm/my-chart --region us-east-1 # Push chart to ECR helm package ./my-chart helm push my-chart-1.0.0.tgz oci://my-account.dkr.ecr.us-east-1.amazonaws.com/helm # Pull chart from ECR helm pull oci://my-account.dkr.ecr.us-east-1.amazonaws.com/helm/my-chart --version 1.0.0

Azure Container Registry

# Login to Azure ACR az acr login --name myregistry # Create repository az acr repository create --name myregistry --repository helm/my-chart # Push chart to ACR helm package ./my-chart helm push my-chart-1.0.0.tgz oci://myregistry.azurecr.io/helm # Pull chart from ACR helm pull oci://myregistry.azurecr.io/helm/my-chart --version 1.0.0

Google Artifact Registry

# Login to GAR gcloud auth print-access-token | \ helm registry login -u oauth2accesstoken --password-stdin https://LOCATION-docker.pkg.dev # Push chart to GAR helm package ./my-chart helm push my-chart-1.0.0.tgz oci://LOCATION-docker.pkg.dev/PROJECT/REPO/helm # Pull chart from GAR helm pull oci://LOCATION-docker.pkg.dev/PROJECT/REPO/helm/my-chart --version 1.0.0

GitHub Container Registry

# Login to GHCR echo $GITHUB_TOKEN | \ helm registry login -u $GITHUB_USERNAME --password-stdin ghcr.io # Push chart to GHCR helm package ./my-chart helm push my-chart-1.0.0.tgz oci://ghcr.io/username/helm # Pull chart from GHCR helm pull oci://ghcr.io/username/helm/my-chart --version 1.0.0
Registry Requirements:
  • OCI registry must support OCI artifacts
  • Helm v3.7+ is required
  • Authentication is handled via docker login
  • Chart versions must follow semver
  • Registry must allow pushing OCI artifacts
Pushing and Pulling Charts to OCI
# Package a chart helm package ./my-chart # Push to OCI registry helm push my-chart-1.0.0.tgz oci://myregistry.azurecr.io/helm # Push with specific tag helm push my-chart-1.0.0.tgz oci://myregistry.azurecr.io/helm/my-chart:1.0.0 # Pull from OCI registry helm pull oci://myregistry.azurecr.io/helm/my-chart --version 1.0.0 # Pull and unpack helm pull oci://myregistry.azurecr.io/helm/my-chart --version 1.0.0 --untar # Install from OCI registry helm install my-release oci://myregistry.azurecr.io/helm/my-chart --version 1.0.0 # Upgrade from OCI registry helm upgrade my-release oci://myregistry.azurecr.io/helm/my-chart --version 1.1.0 # List charts in OCI registry # Using crane or other OCI tools crane ls myregistry.azurecr.io/helm # List tags for a chart crane ls myregistry.azurecr.io/helm/my-chart # Delete a chart version crane delete myregistry.azurecr.io/helm/my-chart:1.0.0
OCI Commands Summary:
  • helm registry login - Authenticate to OCI registry
  • helm package - Package chart before pushing
  • helm push - Push chart to OCI registry
  • helm pull - Pull chart from OCI registry
  • helm install - Install directly from OCI registry
  • crane - Advanced OCI registry operations
Chart Dependencies with OCI
# Chart.yaml with OCI dependencies apiVersion: v2 name: my-app version: 1.0.0 dependencies: - name: postgresql version: 11.0.0 repository: oci://myregistry.azurecr.io/helm - name: redis version: 16.0.0 repository: oci://myregistry.azurecr.io/helm # Update dependencies helm dependency update # Build dependencies from OCI helm dependency build # List dependencies helm dependency list # Use OCI repository with alias dependencies: - name: postgresql version: 11.0.0 repository: oci://myregistry.azurecr.io/helm alias: db # Use OCI repository with condition dependencies: - name: redis version: 16.0.0 repository: oci://myregistry.azurecr.io/helm condition: redis.enabled
CI/CD Integration with OCI
# GitHub Actions workflow name: Push Helm Chart to OCI on: push: tags: - 'v*' jobs: push: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 - name: Install Helm uses: azure/setup-helm@v3 with: version: 'latest' - name: Login to GitHub Container Registry run: | echo "${{ secrets.GITHUB_TOKEN }}" | \ helm registry login ghcr.io -u ${{ github.actor }} --password-stdin - name: Package and Push Chart run: | helm package ./my-chart helm push my-chart-*.tgz oci://ghcr.io/${{ github.repository }}/helm # GitLab CI stages: - package - push package: stage: package image: alpine/helm:latest script: - helm package ./my-chart artifacts: paths: - my-chart-*.tgz push: stage: push image: alpine/helm:latest before_script: - echo $CI_REGISTRY_PASSWORD | helm registry login $CI_REGISTRY -u $CI_REGISTRY_USER --password-stdin script: - helm push my-chart-*.tgz oci://$CI_REGISTRY/$CI_PROJECT_PATH # Jenkins Pipeline pipeline { agent any stages { stage('Package') { steps { sh 'helm package ./my-chart' } } stage('Push to OCI') { steps { withCredentials([string(credentialsId: 'registry-token', variable: 'TOKEN')]) { sh ''' echo $TOKEN | helm registry login myregistry.azurecr.io -u $USER --password-stdin helm push my-chart-*.tgz oci://myregistry.azurecr.io/helm ''' } } } } }
CI/CD Best Practices:
  • Use secrets for registry credentials
  • Version charts with Git tags
  • Automate chart packaging and pushing
  • Implement chart testing before pushing
  • Use OCI for all chart distributions
  • Monitor registry storage usage
Frequently Asked Questions
What is the difference between OCI and traditional Helm repositories?
OCI repositories store charts as OCI artifacts in container registries. Traditional Helm repositories use HTTP servers with index.yaml files. OCI provides better integration with container infrastructure, authentication, and security.
Which Helm version supports OCI?
Helm v3.7+ supports OCI repositories. Older versions of Helm v3 and Helm v2 do not support OCI.
How do I authenticate to an OCI registry?
Use helm registry login <registry> with username and password (or token). For cloud providers, use provider-specific commands like aws ecr get-login-password or az acr login.
Can I use OCI with Chartmuseum?
Yes! Chartmuseum supports OCI mode with OCI_ENABLED=true and OCI_STORAGE configuration. This allows Chartmuseum to act as an OCI registry for Helm charts.
How do I list charts in an OCI registry?
Use tools like crane (from Google) or oras to list repositories and tags. crane ls myregistry.azurecr.io/helm lists all charts in the repository.
Can I use OCI dependencies in Chart.yaml?
Yes! Use repository: oci://myregistry.azurecr.io/helm in the dependencies section of Chart.yaml.
How do I migrate from traditional Helm repositories to OCI?
Package and push existing charts to OCI registries. Update Chart.yaml dependencies to use OCI URLs. Migrate CI/CD pipelines to use OCI commands.
What are the best practices for OCI chart management?
Use semantic versioning, enable registry authentication, implement chart signing, automate CI/CD integration, and monitor registry storage and access.
Related Topics
What is Helm?

Kubernetes package manager
Helm Repositories

Adding, updating, searching
Pushing and Pulling Charts

Chart distribution
Helm Security

Best practices
Helm Best Practices

Production guidelines
Previous: Helm Repositories Next: Pushing and Pulling Charts

OCI repositories represent the future of Helm chart distribution. Adopt OCI for better integration with container infrastructure, improved security, and simplified management.