Argo CD multiple sources for Helm values: when a separate values repository fits
A platform team that consumes a vendor or community Helm chart and keeps its environment values in a separate Git repository can connect the two in one Argo CD Application with the sources field and a $values reference. Argo CD generates manifests for each source separately, then combines them, so the chart stays upstream and the values stay under your change control. Teams reach for this pattern when the chart owner and the environment owner are different people, when values for several environments must be reviewed through their own pull requests, or when the values repository carries access controls the chart repository does not.
When an Application sets sources, Argo CD ignores the singular source field. The chart source names the Helm chart and its version, and a second Git source with a ref name (for example, ref: values) makes that repository available as $values. The chart's valueFiles then point at paths such as $values/envs/prod/values.yaml, which resolve from the root of the referenced repository. A ref source cannot set chart, so it only supplies files. If two sources render the same resource, the last one wins and Argo CD logs a RepeatedResourceWarning, so confirm that no two sources own the same object before relying on the result. Check the exact field names against the multiple sources guide for the Argo CD version you run.
The official guidance is to rethink the design once an Application needs more than two or three sources. Before adding a fourth, test whether a single values repository per environment, a Helm umbrella chart, or one ApplicationSet that generates one Application per environment would be simpler to review and debug. Decide who can change the chart revision and who can change the values, and make that split visible in repository permissions and Argo CD project settings.
How sources combine and what the last-source-wins rule means
Setting the sources list on an Argo CD Application changes how Argo CD reads the application. Argo CD ignores the single source field, generates manifests for each entry in sources separately, and then combines the output into one desired state for the destination cluster. A typical split uses one entry for the upstream chart with a chart and repoURL, and a second entry for your environment repository with a ref name. The chart source renders the templates, while the ref source supplies the values files. Because the two sources are rendered independently, a value you expect to apply can only reach the chart through the $values path reference in valueFiles, which resolves to the root of the referenced repository.
The part that causes the most trouble is what happens when two sources emit the same resource. Argo CD does not reject the overlap. It keeps the object from the last source in the list and records a RepeatedResourceWarning on the Application. The rule is positional, so reordering entries can silently change which Deployment, ConfigMap or Service reaches the cluster. Before you go live, render each source on its own, compare the Kubernetes kinds and names, and confirm that no environment file is meant to replace a chart resource. Also confirm the exact behavior with the version of Argo CD you run, since the warning and merge details are documented in the multiple sources guide.
A ref source cannot set chart, so the chart itself must always come from a chart-bearing source. Plan the repository layout around that constraint: the environment repository holds only values files and any overlays, and the chart version is pinned in the chart source. The multiple sources guide also suggests reconsidering the design beyond two or three sources, because each extra source adds another rendering path to debug. If your environments need many such combinations across clusters, an ApplicationSet that templates one Application per environment is often easier to review, as covered in the sibling section on ApplicationSets.
Configuration options for multiple sources and when each fits
This table compares the four layouts teams use to combine an upstream Helm chart with environment values. Read each row for what Argo CD does with the sources and where the layout starts to strain. The main takeaway is that the separate values repository works well for one or two sources, while a growing number of environments usually points toward ApplicationSets.
| Option | What it does | When it fits or breaks down |
|---|---|---|
| Single source with inline values | One source points at the chart or a repo with values in the Application spec under helm.values | Fits small setups with few values. Breaks down when values for many environments must be reviewed separately from the chart reference |
| Sources list with chart and ref values repo | The sources field lists the chart and a Git source with a ref name, and valueFiles reference $values | Fits teams that keep environment values in their own repository and want Git history and pull request review for them |
| valueFiles paths from the values repo root | A $values reference resolves to the root of the ref repository, so paths such as $values/envs/prod/values.yaml point at files there | Fits when the values repo has a stable folder layout. Breaks down when paths drift between branches or when file names differ across environments |
| Layered sources with two or three entries | Several value files from the ref repo are layered in order, with later files overriding earlier ones | Fits a common base plus one environment override. Breaks down past two or three sources, where the upstream guide suggests rethinking the design |
| Last source wins for repeated resources | If two sources render the same resource, the later source takes effect and Argo CD raises a RepeatedResourceWarning | Fits deliberate overrides. Breaks down when the overlap is accidental and no one notices the warning in the UI |
| Separate Applications per environment via ApplicationSet | A generator produces one Application per cluster or environment, each with its own sources and values | Fits many clusters or environments that share one template. Breaks down less often than layered sources, though generator design needs care |
How to set up a chart and values repository in Argo CD
This sequence produces one Argo CD Application that pulls a Helm chart from its upstream repository and environment values from your own repository, with each source checked before the next one depends on it.
Register the chart and values repositories
Add the upstream chart repository and your values repository to Argo CD so the repo-server can read both. Confirm both repositories show a successful connection status in the Argo CD settings or with the argocd CLI. Since Argo CD 3.0, define repository credentials as Kubernetes Secrets rather than in the argocd-cm ConfigMap, so store the values repository credentials that way. Done when both repositories report a successful connection and no credential appears in plain text in the ConfigMap.
Define the Application with a sources list
Create the Application manifest with a sources list instead of the single source field. Add the chart source first, with repoURL, chart, targetRevision and the chart version, then add the values source as a second entry pointing at your values repository. Argo CD ignores the source field when sources is set, so do not keep both. Check the manifest with a schema or lint step before applying it to the cluster.
Set ref on the values source
Give the values source a ref name, for example values, and leave chart unset on that entry. The ref entry is only a Git source that makes its repository available for reference, so it must not set chart. Confirm the values source has a ref field and that the chart source has no ref. Done when the manifest validates and the chart source is the only entry that names a chart.
Reference $values in valueFiles
In the chart source's helm valueFiles list, reference the values file as $values followed by the path from the repository root, such as $values/environments/production/values.yaml. The $values reference resolves to the root of the ref repository, so the path must start from that root and not from a subfolder of your choosing. Confirm the path against the repository tree at the revision you are syncing.
Confirm the values file path resolves
Before syncing, check that the file exists at the exact path and revision Argo CD will read. A wrong path or a missing file is the most common reason the values do not apply, so compare the path with the repository tree and the targetRevision of the ref source. Done when the path matches a committed file and the Application's manifest preview reflects the values you expect.
Sync and confirm the rendered manifests
Sync the Application and open the rendered manifests in the Argo CD UI or with argocd app manifests. Confirm the resources reflect the environment values, such as replica counts or image tags from your file. Check the application events and logs for a RepeatedResourceWarning, which appears when two sources produce the same resource and the last one wins. Done when the expected values appear in the manifests and no unexpected warning is raised.
Review the design before adding more sources
The multiple sources guide suggests rethinking the design beyond two or three sources. If you need more inputs, such as a second values layer or a patch repository, consider whether an ApplicationSet with per-environment values is a better fit. Confirm the team agrees on which source owns each resource type before adding another source, and record the decision in the repository README.
Multiple sources or ApplicationSets: choosing by situation
When one upstream chart runs in a handful of environments owned by the same team, multiple sources usually stays the simpler choice. The Application keeps a single definition, the chart comes from its upstream repository, and environment values live in one separate repository that the same team reviews. The number of Application resources stays small enough to inspect by hand, and the mapping from environment to values file is easy to read.
- Few Applications: Each environment is one Application, so a reviewer can see the whole deployment in one manifest.
- Clear values path: A
$valuesreference invalueFilespoints at a single environment folder in the values repository. - Low setup cost: No generator, template or cluster registration is needed before the first sync.
- Easy rollback review: A values change shows up as one Git diff against one Application.
- Watch the count: The multiple sources guide suggests rethinking the design beyond two or three sources, so keep the source list short.
Before you commit, confirm that the number of environments will stay small and that one team will own every values file.
When the same chart must reach many clusters, or many teams need the same template with their own parameters, an ApplicationSet usually gives clearer ownership. A generator produces one Application per target, so the template lives in one place and each target is described by data. The Git generator reads directories or files from a repository, and the Cluster generator iterates over clusters registered with Argo CD. Ownership moves from hand-edited Application objects to the data files that generators read.
- Template once: The Application template is defined once, and generated Applications inherit changes to it.
- Data drives targets: Adding a cluster or team means adding a registered cluster or a new directory, not copying an Application.
- Per-target ownership: Team folders or cluster labels map to the people who approve changes for them.
- Consistent naming: Generated names follow a predictable pattern that auditors and operators can search.
- Coordinated changes: A template change affects every generated Application, so review it as a fleet-wide change.
Ask your team whether they want generator output reviewed as the source of truth and whether the template change process needs stricter approval.
Argo CD combines the output of every source in the sources list, and the last source wins when two sources produce the same resource. That rule is manageable with two sources, such as a chart and a values repository. Past two or three sources, such as a chart, a shared base, a team overlay and a secrets reference, the combined output becomes hard to predict and the override order becomes a review burden. The multiple sources guide itself suggests reconsidering the design at that point.
- Override order risk: Each added source can silently replace a resource defined by an earlier one, and the RepeatedResourceWarning is easy to miss.
- Harder review: Reviewers must trace each field back to a source to know which value is in force.
- Split the Application: A generator or several Applications, each with two sources, can keep each layer's ownership separate.
- Document the order: If you keep many sources, write down which source wins for each resource kind.
- Test the render: Compare the rendered manifests after each change instead of trusting the source list.
Check whether the extra sources reflect real ownership boundaries. If they do, that is usually a signal to split the deployment rather than add another source.
The choice is rarely permanent, and the cheapest decision is the one that matches who will review and approve changes. Multiple sources keeps the chart and values in view together for a small team. An ApplicationSet moves the complexity into generator design, cluster registration and RBAC, which pays off when many targets share one template. The sibling ApplicationSets topic covers how generators, cluster registration and rollout guardrails are set up, and the same ownership questions apply to both designs.
- Count the targets: A small, fixed set of environments favors sources, while a growing list of clusters or teams favors generators.
- Map approvals: Decide who approves a values change and whether that person can see the full rendered result.
- Plan growth: Estimate how many Applications a year from now and whether the team can still read them.
- Keep the migration path open: A two-source Application can usually be moved into a generator later if the rendered output stays the same.
- Verify the render: Compare manifests from both designs before switching.
Before you choose, ask your implementation partner or internal team to confirm the target count, the approval owners and how much of the rendered output reviewers must check.
Security risks in splitting chart and values across repositories
Splitting an upstream chart from your environment values creates a second repository that decides what deploys. Each card below is a trust boundary the repo-server, the Git permissions or the Application definition must enforce, and each one is worth checking before the first sync.
Untrusted values repository reaches Helm
The Argo CD repo-server runs Helm and Kustomize on repository content. A values repository is repository content too, so anyone who can push to it can influence what the repo-server renders. Treat the values repository with the same trust level as the chart and the manifests it produces. Confirm which teams can merge to it and whether an external contributor could ever reach it.
Out-of-tree file access in valueFiles
Value file paths are resolved relative to the repository, and a path can point outside the directory you intended. When a $values reference resolves to the root of the values repository, a crafted or careless path can read files you did not plan to expose to rendering. Review each valueFiles entry during code review, and keep the values repository limited to the files that belong to deployments.
Who can change what deploys
Changes to the values repository change live workloads without touching the chart or the Application manifest. A single value, such as an image tag or a replica count, can alter production. Map which groups hold write access, require reviews on protected branches, and decide whether the values repository follows the same change approval rules as application code.
Repository credentials as Kubernetes Secrets
Since Argo CD 3.0, repositories must be defined as Kubernetes Secrets rather than entries in the argocd-cm ConfigMap. Each repository in a multiple-sources Application needs its own credential, so the number of Secrets grows with the number of sources. Confirm who can read those Secrets, restrict access with cluster RBAC, and rotate deploy keys or tokens on a schedule you can name.
RBAC scope on the Application
Update and delete RBAC now apply only to the Application itself, and logs access needs an explicit logs, get permission. A user who can edit an Application can change its sources list and point it at a different values repository. Check which roles hold update rights on Applications inside each AppProject, and confirm that the project's allowed source repositories restrict every source in the list, not just the chart.
Questions teams ask before splitting Helm values into their own repository
Is a separate values repository worth the extra repository?
A separate values repository is worth it when several environments or clusters share one upstream chart and the people who change values are different from the people who maintain the chart. It separates environment configuration from chart code, so changes to values go through their own review and history. The cost is one more repository to secure, access-control, branch and document, plus a rule for which repository owns which change. If one team owns both the chart usage and the values for a single cluster, the extra repository may add more coordination than it removes. Ask your team to list who edits values, how often, and who approves them before deciding.
What does the team need in place before the split?
The team needs a fixed chart version pinned in the application, a clear owner for each values repository, and agreement on the directory layout the $values path will point to. Engineers need to know how Argo CD resolves multiple sources and how a ref source differs from the chart source, because a ref source cannot set chart. You also need a test path, such as rendering the manifests for each environment before merge, and read access for Argo CD to every repository involved. Repository credentials are defined as Kubernetes Secrets, since Argo CD 3.0 no longer reads repositories from argocd-cm.
How long does a typical migration take?
Duration depends on how many applications use inline values today, how many environments and clusters are affected, how much the values differ between them, and how many people must review the change. Teams that have many near-identical values files usually spend most of the time on the comparison and the diff review, not on editing the Application manifest itself. Ask any partner for a written plan that lists each application, the repositories it will read, the cutover order and the verification steps. Do not accept a duration without that breakdown.
Can our own team do this without a partner?
Yes, if your engineers already run Argo CD and Helm in production and have the time to plan the change. The work is mostly configuration: restructuring Application manifests, moving values into a new repository, and checking rendered output. A partner adds value when the migration spans many applications, when repository access and Secrets need a security review, or when your team lacks capacity to run the cutover and verify each environment. Whichever path you choose, confirm the rollback steps in writing before the first sync.
What breaks when two sources produce the same resource?
When two sources in the sources field generate the same resource, the last source wins and Argo CD reports a RepeatedResourceWarning. This is easy to miss because the sync can still succeed while one source's definition is silently replaced. Typical causes are a values repository that includes a manifest copied from the chart, or an extra source that renders a ConfigMap or Secret with the same name. Check the warning in the Application details after every change, keep each source's output distinct, and review the order of the sources list as part of the change.
When are ApplicationSets the better choice?
ApplicationSets are the better choice when the same chart and values structure must be deployed to many clusters or environments and you want Argo CD to generate one Application per target from a template. A generator such as the List, Cluster or Git generator produces the Applications, so adding a cluster becomes a data change instead of a manual copy. Multiple sources are a better fit for a small number of applications with one or two environment repositories. If you find yourself adding more than two or three sources to a single Application, the upstream guide suggests reviewing the design, and an ApplicationSet is often the next step. See the dedicated ApplicationSets topic for generator design and rollout guardrails.
Does a separate values repository change who can deploy to production?
It can, because Argo CD reads the values from the repository you configure, so whoever can merge to that repository can change what gets deployed. Treat the values repository as production configuration: require reviews, restrict who can push to protected branches, and keep the Argo CD project's allowed source repositories as narrow as possible. Confirm how your Git host enforces branch protection and how your Argo CD projects restrict sources before you split the repository. Your compliance and security teams should see the access model before the change goes live.
Operating a split chart and values layout over time
A split layout stays manageable only if each upstream chart bump is reviewed as a rendered change, not as a version number. Before you move the chart version in the Application's sources entry, render the combined output against the current revision and the proposed one, then read the diff of the resulting manifests. Pay attention to resources that appear in both sources, because the last source wins and Argo CD reports this with a RepeatedResourceWarning. A chart bump can introduce a new default object that collides with one your values repository already creates, and the warning is easy to miss in a sync summary. Treat any new RepeatedResourceWarning after an upgrade as a stop condition until someone has explained it.
Put the values repository under the same pull request discipline as application code. Every change to a valueFiles file in the $values repository should show the chart version it targets, the rendered diff where your tooling can produce it, and a named reviewer who owns the environment. Keep the chart version pinned in the Application spec rather than floating, so a values change and a chart change are never merged in one step without review. Ask your team to confirm that the Git provider branch protection on the values repository matches the controls you apply to the chart source, since a write to either source changes what reaches the cluster.
Plan upgrades against the Argo CD release calendar. The project's release process describes a minor release four times a year, and only the three most recent minor versions receive patch releases, so an Argo CD version left behind will stop receiving fixes within that window. Confirm the current support window with the release process page before scheduling your upgrade, and keep the Argo CD version and the multiple sources behavior tested together in a non-production cluster. Upgrades that change how sources or repo-server rendering behave should be read against the upgrade notes for that version before any environment is touched.
How DeployOpen scopes and delivers a multiple sources layout
DeployOpen plans and builds the Argo CD multiple sources layout inside your own infrastructure, separating the upstream Helm chart reference from your environment values repository. We agree the scope in writing before work starts, then hand over the configuration, tests and runbooks your team needs to operate it.
How we scope
- Inventory which Helm charts, chart versions and values repositories each application uses today
- Confirm the Git hosts, branch rules and access groups that control who can change values
- Agree in writing whether the layout stays on a few Applications or moves to ApplicationSets
How we build
- Define each source with a ref for the values repository and map valueFiles to $values paths
- Check that no two sources render the same resource, so last-source-wins never applies silently
- Test manifest rendering in a non-production cluster before any environment syncs from the layout
How we hand over
- Document the source order, ref naming and the RepeatedResourceWarning checks your team should run
- Provide a written record of each Application, its sources and the owner of each values path
- Walk your platform and application teams through a change, from values commit to sync and rollback
How we support
- Offer ongoing support, chart and Argo CD upgrade work and continuous testing as a retainer
- Review the layout when a chart adds sources or the number of sources grows past two or three
- Confirm with your team which upgrade notes apply before each Argo CD minor version change
