How does Helm's oci:// reference address a chart, on the command line and in a Chart.yaml dependency?

## Two ways Helm finds a chart Helm has always been able to fetch a chart from a **classic chart repository**: an HTTP server holding an `index.yaml` that lists every chart name, every version, and the URL of each `.tgz`. You register that server once with `helm repo add`, Helm caches its `index.yaml`, and afterwards you name charts as `myrepo/tileserver`. An **OCI registry** — the same kind of registry that stores container images — is the other distribution target. Here there is no index and nothing to register. The chart's *address is the reference itself*, written with the `oci://` scheme. ## The shape of the reference ``` oci://registry.example.internal/platform-charts/tileserver ^ host ^ path ^ chart name ``` Two rules matter and they are the source of nearly every beginner mistake: 1. **The last path segment is the chart name.** It is not decoration — it must match the `name` field in the chart's `Chart.yaml`. 2. **The chart version is the tag.** You do not write it into the URL with a colon on the command line; you pass `--version`. A chart at version `2.7.14` lives at the tag `2.7.14`. ## On the command line Every command that takes a chart argument takes an `oci://` reference: ```bash helm install tiles oci://registry.example.internal/platform-charts/tileserver --version 2.7.14 helm upgrade tiles oci://registry.example.internal/platform-charts/tileserver --version 2.7.15 helm pull oci://registry.example.internal/platform-charts/tileserver --version 2.7.14 helm show chart oci://registry.example.internal/platform-charts/tileserver --version 2.7.14 helm template tiles oci://registry.example.internal/platform-charts/tileserver --version 2.7.14 ``` `helm template` and `helm show` still need to reach the registry — they render or read locally, but the chart has to be fetched first. What none of these need is a prior `helm repo add`; trying to add a registry as a repository is a category error, because a registry has nothing shaped like an `index.yaml` for Helm to cache. ## In a Chart.yaml dependency When one chart depends on another, the reference is **split across two fields**, and this is where people most often get it wrong. The `repository` field holds the path *up to but not including* the chart name; the chart name goes in `name`: ```yaml apiVersion: v2 name: tileserver-platform version: 1.4.0 dependencies: - name: tileserver version: "2.7.14" repository: "oci://registry.example.internal/platform-charts" ``` Helm joins `repository` and `name` to build `oci://registry.example.internal/platform-charts/tileserver`, then treats `version` as the tag to fetch. Putting the chart name into `repository` as well produces a doubled path that the registry does not have. The `version` field may be an exact version or a SemVer range. With a classic repository Helm resolves a range against the cached `index.yaml`; for an `oci://` dependency there is no index, so Helm asks the registry for the tags published under that path and resolves the range against those. The result is written to the chart's lock file and the chosen version is vendored, exactly as it is for a classic repository — the resolution *source* is what differs, not the mechanism around it. ## Pin the version Because there is no index describing what exists, be explicit. In CI, in a `Chart.yaml` dependency and in any command a human runs against production, name the exact version. A floating reference to a registry is a reference whose meaning is decided by whoever last pushed a tag, and unlike a classic repository there is no local index cache to tell you after the fact what the set of candidates was at the time. ## Versions of Helm OCI support is not new or experimental. It has been generally available since Helm 3.8, and the environment variable that used to gate the feature has been unnecessary ever since — if you see it set in a pipeline, it is a leftover. Helm 4 kept the reference syntax and the command set identical, so an `oci://` reference written for Helm 3 works unchanged.