Confusion about repoURL and path definition in a helm oci application

[mardonner]

(argocd v3.4.3)

Hi,
while going through the docs, I found three different ways to define an helm oci application and I'm a little confused which one I should use.

The User Guide -> Helm and Operator Manual -> Declarative Setup sections tells me to use:

  source:
    chart: nginx
    repoURL: registry-1.docker.io/bitnamicharts  # note: the oci:// syntax is not included.
    targetRevision: 15.9.0

The Userguide -> OCI section tells me to use:

  source:
    path: .
    repoURL: oci://registry-1.docker.io/bitnamicharts/nginx 
    targetRevision: 15.9.0

And Userguide -> OCI special cases section tells me to not have the oci:// prefix, have just the host in repoURL and the rest in the path.

  source:
    path: bitnamicharts/nginx
    repoURL: registry-1.docker.io
    targetRevision: 1.16.1

Which syntax is the correct or preferred one?

And Userguide -> Application Specification tells me that:

  source:
    repoURL: https://github.com/argoproj/argocd-example-apps.git  # Can point to either a Helm chart repo or a git repo.
    targetRevision: HEAD  # For Helm, this refers to the chart version.
    path: guestbook  # This has no meaning for Helm charts pulled directly from a Helm repo instead of git.

But I assume this regards only 'legacy' non-oci helm repos, correct?

[ELHart05]

All three forms are valid. They map to two different mechanisms, and the docs read like they contradict each other because the OCI and Helm guides were written at different times.

Here is the breakdown (current stable is v3.4.3):

1. Native OCI artifact source (added in v3.1, docs). Here repoURL carries the full oci://host/path/chart, there is no chart field, and path selects a subpath inside the pulled artifact. For an OCI Helm chart the whole chart is at the root, so path is .:

source:
  repoURL: oci://registry-1.docker.io/bitnamicharts/nginx
  targetRevision: 15.9.0
  path: .          # for an OCI Helm chart, path must be "."

The docs say exactly this: "In the case of OCI Helm charts ... the path should always be set to .". The artifact is pulled as an OCI artifact and Argo CD detects it is a Helm chart from the mediaType (application/vnd.cncf.helm.chart.content.v1.tar+gzip).

2. Classic Helm-type repo over OCI (Helm docs). This is the older path. repoURL is the registry host plus the namespace (no oci://, no chart name), the chart name goes in chart, and path is not used at all:

source:
  repoURL: registry-1.docker.io/bitnamicharts   # no oci://, no chart name
  chart: nginx
  targetRevision: 15.9.0

Rule of thumb: if you use the chart field, never put oci:// in repoURL. The two are mutually exclusive. Mixing oci:// with the chart/Helm-repo mechanism is what produces the classic looks like 'oci://...' is not a valid chart repository or cannot be reached error (see #10823).

3. The "special cases" form (bare host in repoURL, chart path in path, no oci://) is not a third general option. It applies when you have registered the registry as a Helm-type repository with credentials (e.g. argocd repo add ... --type helm --enable-oci) and Argo CD needs the host alone to match those creds. In that situation you strip oci:// and move the path out of the URL. The docs put it plainly: "The repository URL should not contain the OCI scheme prefix oci://. Also the path should be removed from the repository URL and should be defined instead in the path attribute."

source:
  repoURL: registry-1.docker.io        # matches the registered Helm repo host
  path: bitnamicharts/nginx
  targetRevision: 1.16.1

So, which to use:

• New setups: prefer form 1 (native OCI, oci:// + path: .). It is the actively developed path and also handles plain manifests, Kustomize, Jsonnet, and CMPs from OCI, not just Helm.
• Already using a registered Helm OCI repo with stored creds: stay on form 2 (or form 3 if your repo is registered by host only).
• Pick one and do not blend the oci:// prefix with the chart field.

And yes, your last assumption is correct: the Application Specification example with repoURL: https://...git and path: guestbook is the git/legacy-Helm-repo case. path there is git-only and has no meaning for charts pulled from a Helm repo, which is exactly what that inline comment is telling you.