Skip to content
Tutorials Center
My learning

Topics

Lesson 25 of 38 ยท Repositories and OCI

Chart Repositories: Adding, Searching and Hosting

Use helm repo add, update and search, understand index.yaml, and host your own HTTP chart repository on static storage, with a runnable index.yaml generator stand-in.

A chart that lives only on your laptop helps nobody. To share charts, teams publish them to a repository. The classic Helm repository is surprisingly simple: a web server that serves packaged charts (.tgz files) plus one index file, index.yaml, that lists them. Anything that can serve static files, such as an object-storage bucket, GitHub Pages or nginx, can be a chart repository.

Using repositories

Add a repository under a local nickname, refresh its index, and search:

Terminal
helm repo add stable-demo https://charts.example.com/stable
helm repo update
helm search repo stable-demo/redis
helm search repo redis --versions
helm show chart stable-demo/redis --version 20.1.7
helm install cache stable-demo/redis --version 20.1.7

What each command does:

  • helm repo add NAME URL downloads the repository's index.yaml and remembers the name in your local config (helm env shows the paths).
  • helm repo update re-downloads every index. Like apt update, it does not change anything installed.
  • helm search repo KEYWORD searches local copies of the indexes. Add --versions to see all versions instead of only the newest, and --devel to include pre-releases.
  • helm repo list and helm repo remove NAME manage the list.
  • helm pull stable-demo/redis --untar downloads a chart to inspect it without installing.

Private repositories take credentials: helm repo add --username U --password-stdin NAME URL. Never put a password on the command line in a shared CI log; read it from stdin.

The anatomy of index.yaml

The index maps each chart name to a list of versions. Every entry carries the chart's metadata and where to download it:

YAML
apiVersion: v1
entries:
  webapp:
    - apiVersion: v2
      name: webapp
      version: 0.3.0
      appVersion: "1.8.2"
      description: A demo web application
      created: "2026-03-02T10:00:00Z"
      digest: 1f0c9d...
      urls:
        - https://charts.example.com/stable/webapp-0.3.0.tgz
    - apiVersion: v2
      name: webapp
      version: 0.2.0
      urls:
        - https://charts.example.com/stable/webapp-0.2.0.tgz
generated: "2026-03-02T10:00:05Z"

The digest is a SHA-256 of the package so a client can detect corruption. The urls can be relative to the repository URL, or absolute and point to another host, for example a CDN.

Hosting your own repository

The workflow has four steps:

Terminal
# 1. package every chart into a folder
helm package charts/webapp charts/worker --destination ./public

# 2. generate (or merge into) the index
helm repo index ./public --url https://charts.example.com/stable

# 3. upload ./public to static hosting
aws s3 sync ./public s3://charts-bucket/stable --acl public-read

# 4. users add it
helm repo add mycharts https://charts.example.com/stable

helm repo index scans the folder for .tgz files and writes index.yaml. To add a new version without losing old entries, pass --merge existing-index.yaml. A repository should keep old versions available forever: someone's Chart.lock still points at them.

The stand-in below builds an index from package filenames, a miniature of what helm repo index does (the real command reads each package's Chart.yaml and computes digests).

Python Stand-in: build index.yaml from packages

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Entries are sorted newest first, which is why helm search repo without --versions shows the top one.

Hosting options compared

Option Pros Cons
Object storage (S3, GCS, R2) Cheap, fast, no server You regenerate and upload the index yourself
GitHub Pages with chart-releaser Free, automated from Git Public by default
ChartMuseum or similar server Upload API, authentication A service to run
OCI registry Same place as images, native auth Different commands (next lessons)

Many organizations are moving to OCI registries because they already run one for container images. Classic repositories still matter: a huge share of public charts, and every old tutorial, use them.

Versioning and immutability

Treat a published name-version.tgz as immutable. If you must change a chart, bump the version. Overwriting a package breaks the digest in everyone's lock files, and caches such as CDNs may serve the old copy for hours. Use pre-release versions (0.4.0-rc.1) for testing: they are invisible to helm search repo unless --devel is set, and ranges like ^0.3.0 skip them.

Troubleshooting

  • "no cached repo found" or stale results: run helm repo update.
  • 404 on download: the urls in index.yaml do not match where files were uploaded; regenerate with the right --url.
  • Two repositories with the same chart name: always refer to charts as repo/chart.
Python Stand-in: why pre-releases hide from search

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What does helm repo update do?

    It refreshes the local copy of each index.yaml; installed releases are untouched.
  2. 2. Which command creates index.yaml for a folder of packaged charts?

    helm repo index scans .tgz files and writes index.yaml, optionally with --url and --merge.
  3. 3. Why should published chart versions be immutable?

    Consumers pin versions and digests; changing content under the same version breaks reproducibility.
  4. 4. Which flag shows pre-release versions in helm search repo?

    --devel includes versions such as 1.0.0-rc.1.

Summary

  • A Helm repository is static files: packaged charts plus index.yaml.
  • Use repo add, repo update, search repo and pull to consume; package and repo index to publish.
  • Keep old versions online and never overwrite a published version.

Next: Packaging, Versioning and Provenance