To understand Helm repositories we first need a handful of simple words: package manager, chart, release, repository and version.

So what exactly is a Helm repository?

A Helm repository is a simple server that holds two kinds of things: packaged charts, each stored as a compressed archive file, and one catalogue file that lists every chart and every version available. When you tell Helm about a repository, it downloads the catalogue and remembers it. From then on, you can search the catalogue, ask for a chart by name and version, and Helm fetches the right archive and installs it.

The important idea is that a repository is deliberately simple. It does not need special software. Anything that can serve static files over the web, such as a small web server, a storage bucket or a page-hosting service, can act as a repository as long as the catalogue and the archives are in the right places. This simplicity is why so many people and companies publish charts.

The three promises of a repository

A short history

The first generation of Helm shipped with a big shared repository of community charts, and for a while that shared shelf was the way most people found software. As the project grew, the community moved from one giant shared shelf to many independent repositories run by the projects themselves, and a discovery website appeared that lets people search across them. More recently, Helm gained the ability to store charts in the same kind of registries that already hold container images, a style called OCI. Today both the classic style and the registry style are in use, and this guide covers both.

A chart is only useful if people can get it, trust it and get the same one every time. Repositories exist to make that easy.

Sharing recipes by hand is a mess

Suppose a team writes a chart for its application. How do the other teams get it? Emailing a folder is slow. Copying files between laptops means everybody ends up with a different edition. Storing charts inside each application’s code repository ties the recipe to one project and makes reuse awkward. And nobody can tell which edition is the newest, or which one is running in production.

What people did before

flowchart LR
  subgraph W["Without a repository"]
    A1["Team writes a chart"] --> B1["Copies sent by chat or email"]
    B1 --> C1["Many different editions"]
    C1 --> D1["Nobody knows what is deployed"]
  end
  subgraph V["With a repository"]
    A2["Team packages a numbered chart"] --> B2["Publishes it to the repository"]
    B2 --> C2["Everyone installs by name and version"]
    C2 --> D2["Same result every time"]
  end
    

Reading Figure 1

The left half shows the world without a repository. A team writes a chart and sends copies around by chat or email. Soon there are many editions, and nobody can say what is deployed. The right half shows the calmer world. The team packages the chart with a version number and publishes it to the repository. Everyone else installs it by name and version, and because a given version never changes, the result is the same for everyone, every time.

A few building blocks appear again and again around repositories. Learn them once and the rest will follow.

Two versions, two meanings

Every chart carries two numbers that people mix up. The chart version describes the recipe itself. If you change a template, a default setting or the way the chart works, the chart version goes up. The application version describes the software the recipe installs, such as the release number of a web server. A new release of the software may come without any change to the recipe, and a new recipe may install the same software. Repositories index charts by chart version, because that is what identifies a unique package.

Semantic versioning in plain words

Chart versions follow a widely used three-part scheme: a major number, a minor number and a patch number, separated by dots. A patch increase means small fixes. A minor increase means new features that do not break existing users. A major increase means changes that may break existing users. When you ask for a chart, you can name an exact version or a range, such as any patch of a certain minor edition. Pinning an exact version gives repeatable installs; using ranges gives automatic fixes at the cost of change.

Classic repositories and registry-based storage

A classic repository is a web location with a catalogue file and archives beside it. A registry-based store keeps charts in the same kind of registry that holds container images. There is no single catalogue file; each chart is addressed by a registry address, a name and a version tag. Both styles work with the same Helm tool, but they behave differently for searching, authentication and publishing, as we will see.

Discovery is not hosting

A public website exists where people search for charts published across many repositories. It is a discovery service: it indexes information about charts and points you to the repository that actually hosts them. It does not store your charts for you. When you add a repository you are talking to the real host, not to the discovery website.

Several pieces cooperate between the person who writes a chart and the cluster that runs it. It helps to see who talks to whom.

flowchart TB
  DEV["Chart author"] -->|"Packages a numbered chart"| ARC["Chart archive"]
  ARC -->|"Published to"| REPO["Repository: archives plus catalogue or registry entries"]
  CI["Publishing pipeline"] -->|"Updates the catalogue"| REPO
  CLIENT["Helm command on a laptop or pipeline"] -->|"Adds and refreshes"| CACHE["Local cache of catalogues"]
  CACHE -->|"Reads catalogue from"| REPO
  CLIENT -->|"Downloads the chart archive"| REPO
  CLIENT -->|"Renders templates and sends objects"| API["Kubernetes API server"]
  API --> REL["Release records stored in the cluster"]
    

Reading Figure 2 piece by piece

Start at the top left. A chart author packages the chart into a numbered archive and publishes it to the repository, usually through an automated pipeline that also updates the catalogue. On the user’s side, the Helm command keeps a local cache of the catalogues of the repositories it knows. When the user asks for a chart, Helm consults the cache to find the right version, downloads that archive from the repository, renders the templates into ordinary Kubernetes objects, and sends them to the cluster’s API server. The cluster stores a record of the release so that later upgrades and rollbacks know what was installed.

Notice that the repository never talks to the cluster. It is a passive shelf. All the work happens in the Helm command on the user’s machine or in a pipeline. This fact has consequences for security and for network design that we explore later.

The parts, one by one

Where a repository can live

Because a classic repository only needs to serve files, it can live almost anywhere: a small web server you run, an object storage bucket behind a web address, a free page-hosting service attached to a code repository, or a dedicated chart-hosting product. Registry-based storage lives in a container registry, which many organisations already run. Cloud providers also offer managed registries that accept charts. The best home is usually wherever your team already manages access, backups and availability.

Now let us open the box. We will look at what is inside the catalogue, and how Helm turns “install this chart” into a downloaded, checked package.

What the catalogue contains

The index file of a classic repository is a plain text document. For every chart name it lists every published version, and for each version it records the chart’s description, its chart and application versions, the date it was created, the list of dependencies, one or more download addresses and a digest. The digest is a fingerprint of the archive: a long string computed from the file’s contents, which changes completely if even one byte of the file changes. Helm uses it to check that the downloaded file is the one the catalogue promised.

flowchart TD
  S["User asks to install a chart by name and version"] --> A{"Is the repository known and its catalogue cached?"}
  A -->|"No"| R["Add repository and download the catalogue"]
  A -->|"Yes"| B{"Does the catalogue contain that chart name?"}
  R --> B
  B -->|"No"| X1["Error: chart not found"]
  B -->|"Yes"| C{"Does a version match the request or range?"}
  C -->|"No"| X2["Error: no matching version"]
  C -->|"Yes"| D["Download the archive from its address"]
  D --> E{"Does the digest match the catalogue?"}
  E -->|"No"| X3["Error: file changed or corrupted"]
  E -->|"Yes"| F["Unpack, merge settings, render templates"]
  F --> G["Send objects to the cluster and record the release"]
    

Reading Figure 3

The flow has several checkpoints, each a chance for a clear error. First, Helm needs a cached catalogue for the repository, and downloads it if it does not have one. Second, the chart name must appear in the catalogue. Third, a version must match what the user asked, either exactly or within a range; if not, Helm says no version matches. Fourth, Helm downloads the archive and compares its fingerprint to the catalogue’s digest, refusing files that differ. Only then does it unpack the chart, merge the default settings with the user’s own, turn the templates into ordinary Kubernetes objects and send them to the cluster.

How registry-based storage differs inside

In registry style there is no catalogue file. A chart is stored as an artefact in a registry, addressed by a registry host, a path and a tag that carries the version. When Helm is asked to install, it contacts the registry, authenticates if required, asks for the artefact with that tag, downloads its layers and unpacks them. The registry itself keeps a digest for each artefact, and tags can often be locked so that they never point at anything else. Because there is no index to refresh, there is no add or update step, and versions appear the moment they are pushed. The trade-off is discovery: to list versions you ask the registry for the tags of a given chart path, and to search across many charts you need a discovery site or the registry’s own interface.

This style also inherits everything registries already do well: fine-grained permissions, robot accounts for pipelines, replication between regions, scanning and signing support, and storage that is built for large numbers of artefacts.

Searching happens locally

When you search for a chart in your added repositories, Helm searches the cached catalogues on your own machine, not the servers. That makes searching fast and lets it work offline, and it also means results are only as fresh as your last refresh. Refreshing downloads the newest catalogues again. If a colleague published a new version an hour ago and you have not refreshed, your searches will not show it.

Let us follow one chart from the day it is written to the day a release using it is removed.

sequenceDiagram
  participant A as Author
  participant P as Pipeline
  participant R as Repository
  participant H as Helm client
  participant C as Cluster
  A->>P: Change chart and raise the version
  P->>P: Check the chart and package it
  P->>R: Upload archive and update catalogue
  H->>R: Refresh catalogue
  R-->>H: New catalogue
  H->>R: Download archive for chosen version
  R-->>H: Archive
  H->>H: Verify digest and render templates
  H->>C: Create or upgrade objects
  C-->>H: Release recorded
  H->>C: Later, roll back or uninstall
    

Reading Figure 4

The story begins with the author changing the chart and raising its version. A pipeline checks the chart, packages it, uploads the archive and updates the catalogue. Later, a user’s Helm client refreshes the catalogue, sees the new version, downloads the archive, checks the digest and renders the templates. It then creates or upgrades objects in the cluster, which records the release. If something goes wrong, the user can roll back to a previous revision or uninstall the release. Notice that the repository takes part only in the middle steps; it never touches the cluster.

Six stages of a chart’s life

What if something goes wrong?

If the repository is unreachable when a user installs, the download fails, and installs from that repository stop, while releases already running in the cluster are unaffected. If a published version is faulty, the fix is to publish a new, higher version, not to change the old one. Changing a published version breaks the promise of repeatability, and causes digest mismatches for anyone who cached the old file. If a version is deleted from the repository, pipelines that pinned it will fail to build, which is why many teams mirror what they depend on.

There are several ways to host charts. Each has its own personality, strengths and traps.

flowchart TB
  subgraph A["Style A: Classic web repository"]
    A1["Catalogue file plus archives on a web server or bucket"] --> A2["Helm adds it by address and caches the catalogue"]
  end
  subgraph B["Style B: Registry-based storage"]
    B1["Charts stored in a container registry as artefacts"] --> B2["Helm addresses each chart by registry path and version"]
  end
  subgraph C["Style C: Chart-hosting product"]
    C1["A product with an interface, access control and upload features"] --> C2["Speaks the classic style, the registry style, or both"]
  end
  subgraph D["Style D: Local folder or source repository"]
    D1["Chart folder used directly from disk or from version control"] --> D2["No catalogue at all"]
  end
    

Reading Figure 5

Each box shows a different way of hosting. In style A, a catalogue file and the archives sit on any web server or storage bucket, and Helm adds the address and caches the catalogue. In style B, charts are stored in a container registry beside your images, and each chart is addressed by a registry path and a version. In style C, a dedicated product adds a web interface, access control and upload features, and may speak both styles. In style D, there is no repository at all: you point Helm directly at a chart folder on disk or in version control.

Style A: the classic web repository

This is the original and simplest style. The publisher packages charts, places the archives on a web location, and runs a small step that builds or updates the catalogue file. Users add the address and can then search and install. It works with static hosting, which is cheap and reliable. Access control is limited to whatever the web host supports, such as basic credentials or signed addresses.

Style B: registry-based storage

Modern Helm can store charts in the same kind of registry that holds container images. Each chart name lives at a registry path, and each version is a tag. There is no catalogue file to refresh, so there is no add or update step; you refer to the chart’s full address when you install. Organisations that already run a registry get charts, authentication and permissions with the same system that holds their images. Listing and searching across a registry work differently, because there is no single catalogue.

Style C: chart-hosting products

Some products are built specifically for chart hosting or for general artefact hosting, including charts. They add a web interface, users and teams, access rules, upload features, replication between sites and security scanning. They usually speak the classic style, the registry style, or both, so that different users can use whichever their tooling prefers.

Style D: no repository at all

Helm can install straight from a chart folder or archive on disk, and pipelines often keep a chart in the same source repository as the application. This is fine for a chart used by one project. It stops scaling when many teams need the same chart, because there is no shared numbered catalogue.

A single table cannot decide for you, but it shows the shape of the differences at a glance.

Testing a repository before you trust it

A short experiment beats a long debate. From a clean machine, add the repository, refresh, search for a known chart, list its versions and install one into a test cluster. Then try to break things on purpose. Request a version that does not exist and confirm the error is clear. Use an expired or wrong credential and confirm that access is refused. Rename nothing, yet republish the same version in a test copy and watch how caches and digests react. Verify a signed chart with the right key and again with the wrong one. Block the repository’s address and confirm that pipelines fail fast with a readable message. Keep the results in your team’s notes together with the Helm version, and rerun the same experiment after every upgrade of the host or the client. Ten minutes of testing here saves hours of guessing during a real incident.

Places charts commonly live

Naming and organising charts

Good names make a repository easy to live with. Choose short, clear chart names that describe the application, not the team that wrote it. Keep one chart per application or per closely related bundle, and split unrelated things apart. Write a useful description and keywords in each chart’s metadata, because they power searching. Decide on a convention for repository names and stick to it, so that everyone adds the same repository under the same friendly name, which keeps documentation and pipelines consistent. Mark charts that are experimental or deprecated clearly, and explain in the description where users should go instead. A little discipline here keeps a catalogue readable when it holds hundreds of charts.

Public versus private

Public repositories are open to everyone, which suits open-source software and shared examples. Private repositories restrict access to a company or team, which suits internal applications and charts containing organisation-specific defaults. Many companies use both: they consume public charts from projects, often through a mirror they control, and publish their own charts to a private repository. Private hosts typically ask for credentials, which the Helm command can store or receive from a pipeline.

A chart is a set of instructions that will run with real permissions in your cluster. Trusting a repository means trusting the instructions it hands you.

What can go wrong

Layers of protection

Who is allowed to publish?

Reading charts and publishing charts are very different powers. A person who can publish to a repository can put instructions in front of every consumer who trusts it, including automated pipelines that install without a human looking. Treat publish rights as a sensitive permission. Limit them to a small set of pipelines and a few named people, require review before anything is published, log every upload, and alert on unexpected changes to the catalogue. Consider separate repositories for stable and experimental charts, so that a trial upload can never reach production consumers by accident. Consumers should know exactly which repositories are approved, and pipelines should refuse to install from anywhere else.

Signing charts

A provenance file is a small signature stored beside a chart archive. The publisher signs the package with a private key, and users verify it with the matching public key. This proves two things: the package was signed by the holder of that key, and it has not changed since. Unlike the digest in the catalogue, the signature does not depend on trusting the repository host, so it defends against a compromised or malicious host. Signing only helps if users actually verify, and if they trust the right public keys. Registry ecosystems also offer their own signing approaches.

Trust the chart, then check the images

Verifying a chart tells you the recipe is genuine. It does not tell you the recipe is wise. A chart can point at container images from anywhere. A careful pipeline renders the chart into plain objects, inspects them for images, permissions and settings, scans the images, and only then allows installation. Many teams also enforce rules in the cluster itself, so that even an approved chart cannot create a privileged container by accident.

Handling repository credentials

Private repositories need credentials, and credentials are secrets. Give each person or pipeline its own account, so that access can be revoked individually and every download is attributable. Prefer short-lived tokens issued through your company’s login system over long-lived passwords. Give pipelines that only install charts read-only access, and give the far smaller set of publishing pipelines write access. Keep credentials in a proper secrets system, and never in chart folders, values files, shell history or chat messages. Helm stores logins in a local configuration file on the machine where they were entered, so protect build machines, and clean up after temporary jobs. When someone leaves the team, remove their account, and rotate any shared credential they knew.

Hardening checklist

There is no single best repository, only the best fit for your team, your tools and your risk. A few questions get you most of the way.

flowchart TD
  A["Where should my charts live?"] --> B{"Is the chart used by only one project?"}
  B -->|"Yes"| C["Keep it beside the application source"]
  B -->|"No, many teams share it"| D{"Do I already run a container registry?"}
  D -->|"Yes"| E["Registry-based storage"]
  D -->|"No"| F{"Do I need a web interface, teams and governance?"}
  F -->|"Yes"| G["Chart-hosting product"]
  F -->|"No"| H["Classic web repository on static hosting"]
    

Reading Figure 6

Begin with the top question: is the chart used by only one project? If yes, keeping it beside the application’s source is simplest, and no repository is needed. If many teams share it, ask whether you already run a container registry. If yes, registry-based storage reuses what you have, including permissions. If not, ask whether you need a web interface, teams and governance. If yes, a chart-hosting product fits. If not, a classic repository on static hosting is the cheapest, simplest answer.

The questions behind the chart

A repository is on the critical path of every installation and every pipeline that uses it. Its speed and uptime shape your delivery.

Where the time goes

Ways to go faster and stay safer

Cache catalogues and archives in your pipelines, and refresh them only when needed. Mirror the public charts you rely on into a repository near your builds. Keep catalogues small by splitting unrelated charts into separate repositories, or by moving to registry-style storage where there is no big index. Put a content delivery network or caching layer in front of busy public repositories. Vendor critical dependencies into your own chart folders when you need builds that never touch the outside world.

Availability: what depends on the repository

Once a release is running, the repository is not needed for the application to keep working. The pods, services and configuration live in the cluster. What depends on the repository is the act of installing, upgrading and rebuilding. If the repository is down, you cannot deploy new versions or spin up new environments from scratch, which can be serious during an incident. Treat the repository as part of your delivery infrastructure and give it a matching level of reliability, backups and monitoring.

Running a mirror

A mirror is a repository you control that holds copies of the public charts you depend on. To run one, list the charts and versions your systems actually use, download the archives, scan and review them, and upload them to your own repository or registry under names your teams recognise. Point pipelines at the mirror instead of the public source. When a team needs a new chart or a new version, they request it, someone reviews it, and it is added to the mirror. This adds a small step to adoption and gives you a permanent, private copy, a place to enforce security rules, protection from upstream deletions and renames, and faster downloads from a nearby host. Automate the copying and the scanning so that the mirror is a convenience rather than a chore.

Every choice buys something and costs something. Here is an honest ledger for using Helm repositories.

Trade-offs in plain words

The first trade-off is simplicity against governance. A static classic repository is the simplest thing that works, but offers little control over who publishes or reads. A hosting product adds control and audit, at the price of running and paying for it.

The second is convenience against safety. Pulling charts straight from a public repository is quick. Mirroring, pinning and reviewing them is slower, and it protects you from upstream surprises. Most teams begin quick and add safety as their systems matter more.

The third is freshness against stability. Version ranges bring in fixes automatically, and they also bring in changes you did not test. Exact pins are stable and need someone to update them deliberately, which is why many teams pair pinning with automated update proposals that go through review.

The fourth is catalogue against registry. A single catalogue file makes discovery easy and grows unwieldy. Registry-style storage scales and integrates with your existing permissions, and makes browsing less convenient.

When a chart cannot be found or downloaded, the message usually names the stage that failed. A calm routine finds the cause quickly.

Symptoms and where to look

A calm troubleshooting routine

First, check the address. A single wrong character in the repository address is the most common cause of failure. Second, check reachability from the same machine that failed, since pipeline machines often sit behind proxies or firewalls that laptops do not. Third, refresh the catalogue and list what versions Helm now sees. Fourth, check credentials for private hosts, including expiry. Fifth, check certificates. Sixth, compare the requested version or range with the versions actually listed, remembering that pre-release versions are usually hidden unless requested. Seventh, check the chart’s dependencies and their repositories. Eighth, look at the host itself: is it up, is disk space available, are rate limits being hit?

A second worked example: the private repository that stopped working

A pipeline that installed charts from a private repository begins failing with an unauthorised error. The address and network are fine, so the team turns to identity. The pipeline uses a token issued three months ago, and tokens expire after ninety days. Nobody had noticed because the token was created by a colleague who has since changed teams. The fix is a fresh token, stored in the secrets system and issued to a dedicated pipeline account, with an alert set for seven days before expiry. The team also writes down who owns the pipeline account. The lesson is that many repository outages are really credential lifecycles that nobody owned.

What to monitor all the time

Track the repository’s availability and response time, certificate expiry dates, storage capacity, failed authentication attempts, and pipeline failures at the download step. For publishers, track whether the catalogue is updated after each publish and whether uploads succeed. Alert on certificate expiry weeks in advance, because a lapsed certificate stops every installer at once. Synthetic checks that add the repository and fetch a small chart from a pipeline machine catch problems before real deployments do.

A pattern is a proven way of solving a repeated problem. An anti-pattern is a tempting habit that keeps causing pain.

Patterns worth adopting

Anti-patterns to avoid

This chapter gathers the advice into checklists you can keep beside your desk.

Best practices

Common mistakes

Managing dependencies well

Charts often depend on other charts, such as a database or a cache. Each dependency names a chart, a version or range, and the repository where it lives. Helm downloads dependencies into the chart’s own folder and records exact versions in a lock file. Treat the lock file like any other important file: commit it, review changes to it, and rebuild from it in pipelines so every build resolves the same versions. Prefer to keep dependency repositories inside your organisation, mirrored from upstream, so that a single external outage does not stop every build. And keep dependency trees shallow; a chart that depends on five charts that each depend on five more is hard to reason about and hard to secure.

A publishing checklist

Before publishing a new chart version, walk through a short list. Raise the version according to semantic versioning. Update the application version if the software edition changed. Lint the chart and render it against several sets of values. Run policy and security checks on the rendered output. Update the change notes. Package and sign. Upload the archive. Update the catalogue or push to the registry. Verify by adding the repository from a clean machine and installing the new version into a test cluster. Announce the release to users. Ten minutes on this list prevents most of the problems described in this article.

These generic stories, based on common patterns rather than any specific company, show how the ideas play out.

Three worked scenarios: thinking like a designer

A short mental checklist for a new repository

Before creating a repository, pause and walk through a short list. State who will consume the charts and how private they must be. Decide the style: classic, registry or product. Decide who may publish and how credentials will be issued. Decide how versions are numbered and that they are immutable. Decide how charts are signed and verified. Decide how public dependencies are mirrored. Decide how you will back up and monitor the repository. Decide how users discover charts. Write it all on one page. Ten minutes on this list prevents most of the problems in this article.

Quick answers to the questions beginners ask most often.

This post was written without live web research. Please verify version-sensitive details, such as registry support, command names and the current addresses of public repositories, against the official documentation for the Helm version you use.

Let us close the loop, returning to the cookbook shop from the start of this article.

Just as a good cookbook shop keeps numbered editions, a clear catalogue and reliable stock, a Helm repository keeps numbered chart versions, a catalogue that Helm can read and packages that never change once published. Helm consults the catalogue, downloads the exact package you asked for, checks it, and installs it into your cluster, and the repository itself never touches the cluster.

You met the problem of sharing recipes by hand, the building blocks of charts, catalogues and versions, and the architecture that connects authors, repositories, the Helm client and the cluster. You followed a chart’s life, compared classic and registry-style hosting, and learned about security, performance, trade-offs, troubleshooting and the mistakes that trap teams most often.

Version drift and things to verify

The Helm ecosystem changes steadily. Registry support arrived after the original repository style, command details and defaults have shifted between releases, popular public repositories have moved, been renamed or been retired, and hosting products have come and gone. Because this article was written without live web research, treat version-specific statements as a starting point. Before relying on a feature in production, read the official documentation for the Helm version you use, try the behaviour in a test cluster, confirm the current address of any public repository, and record the versions in your team’s notes so upgrades prompt a re-check.

A small glossary to keep nearby

Key takeaways