Deploying Helm charts with Argo CD: what changes from helm install
Argo CD inflates Helm charts with helm template and then owns the release lifecycle, so a platform team moving charts from helm install or CI scripts should expect the control plane, not Helm, to decide when resources are created, updated and removed. The practical consequence is that helm list will not show the release, and that Helm's own release history and rollback commands no longer describe what is running. Teams need this capability when they want Git to be the record of what is deployed, when several clusters receive the same chart with different values, or when CI jobs that currently run helm upgrade are becoming hard to audit. Argo CD is released under the Apache License 2.0 (SPDX: Apache-2.0), and the project itself does not sell a paid edition, so the decision rests on the operating cost of your own installation.
Before migrating, map each existing release to an Application and decide the release name that will appear in rendered manifests. Argo CD uses the Application name as the release name unless you set one, so a chart rendered under a different name can produce resource names that clash with objects already in the cluster. Hooks need the same review. Helm pre-install and pre-upgrade hooks become PreSync phases, post-install and post-upgrade hooks become PostSync, and hook-weight becomes a sync wave. Rollback and test hooks are ignored, and defining any Argo CD hook in the chart makes Argo CD ignore all Helm hooks. A database migration job that relied on a Helm test hook for verification will therefore not run, and the team should confirm where that check will live.
Value precedence also changes during migration. In Argo CD, parameters override valuesObject, which overrides values, which overrides valueFiles, which overrides the chart's own values.yaml. Review every helm install --set flag and every values file in CI, because each one must be re-expressed in the Application spec or a referenced file. Repository credentials for private chart repositories are defined as Kubernetes Secrets in the Argo CD namespace, consistent with the 3.0 change that removed repository configuration from argocd-cm. Ask your team to confirm the chart source type, the credential scope and the exact precedence in the version you run by checking the Argo CD Helm guide before cutover.
Why helm list does not show Argo CD releases
Argo CD uses Helm only to inflate the chart. It runs helm template to produce manifests, then Argo CD applies and tracks those manifests itself, so Helm never records a release. An operator who runs helm list against the destination namespace will see nothing for an Argo CD-managed application, and that is expected behavior, not a broken install. The Application resource in the argocd namespace (or the namespace where Applications are allowed) is the record of what was deployed, which revision it tracks, and whether it is in sync.
This changes how you handle rollback, history and troubleshooting. helm rollback and helm history will not work on these releases because Helm holds no release state to roll back to. Rollback in Argo CD means reverting the commit or chart version in Git and letting Argo CD sync it, or using the history view in the Argo CD UI or CLI, which keeps prior synced revisions. Your runbooks should name Argo CD as the first place to look, and your on-call engineers should know the argocd app commands they will need before an incident. Confirm current rollback behavior for your Argo CD version in the Helm guide, since the supported options depend on how automated sync is configured.
Before you migrate an existing Helm release, decide who owns it. Running helm upgrade by hand on a release that Argo CD also manages will fight Argo CD's sync loop, and a release installed with helm install will not be picked up by Argo CD unless its resources are adopted. Write this rule into your change process, and check the Argo CD Helm guide and Argo CD FAQ for the current guidance on tooling that calls Helm directly.
Value sources and precedence in Argo CD
This table lists the five places Argo CD reads Helm values from, ordered from highest to lowest precedence, with what each fits and its main trade-off. Read it top down: a value set higher in the list overrides the same key set lower down, so check the top rows first when a rendered value is not what you expected.
| Value source | Precedence | Best fit | Trade-off |
|---|---|---|---|
| parameters | 1 (highest) | One or two overrides set per Application, such as an image tag promoted by a pipeline | Easy to change in the UI, but hard to review in Git and easy to forget when the Application is recreated |
| valuesObject | 2 | Inline values kept in the Application manifest, often generated by an ApplicationSet per cluster | Values sit in the Application resource rather than a values file, so large blocks make the manifest harder to read |
| values | 3 | A string of inline YAML in the Application spec for short, environment-specific settings | Works for small overrides, but mixing it with valuesObject makes precedence harder to trace |
| valueFiles | 4 | Environment files in your Git repository, such as values-prod.yaml, that the team reviews through pull requests | Files are resolved relative to the chart path, so paths must be checked when the chart or repository layout changes |
| Chart values.yaml | 5 (lowest) | Defaults shipped by the upstream chart, used as the base for every environment | Changes come with chart upgrades, so pin the chart version and review the default values before each upgrade |
| Release name | Not a value source | Defaults to the Application name; set it explicitly when names must match an existing Helm release or stay stable across renames | Renaming the release changes generated resource names, so confirm the impact on running workloads before changing it |
How Helm hooks map to Argo CD sync phases
Argo CD does not run Helm hooks the way helm install does. It translates the hooks it recognizes into its own sync lifecycle: pre-install and pre-upgrade hooks become PreSync hooks, post-install and post-upgrade hooks become PostSync hooks, and the helm.sh/hook-weight annotation becomes an Argo CD sync wave. A database migration Job that Helm ran before an upgrade therefore runs before Argo CD applies the rest of the manifests, and a smoke-test Job that Helm ran afterward runs after the sync completes. Because the mapping is by phase rather than by Helm's own release lifecycle, the ordering you get in Argo CD is the one you must verify, not assume.
Two categories of hook are not carried over. Rollback hooks and test hooks are ignored, so a helm test Job or a pre-rollback cleanup step in the chart will not run under Argo CD. Anything that depended on those hooks needs a replacement, such as a separate Argo CD hook, a pipeline step, or an explicit runbook. The more important rule is that defining any Argo CD hook annotation on a resource makes Argo CD ignore all Helm hooks in that chart. A chart that already has a working PreSync Job can silently lose its PostSync Job once a team adds an Argo CD hook for a different reason.
Before migrating a chart, list every hook template by rendering it with helm template and searching for the helm.sh/hook annotation, then record each hook's phase, weight and deletion policy. Confirm the hook behavior against the Argo CD Helm guide for the Argo CD version you run, because the mapping rules are documented there. Test the sync in a non-production cluster and check that jobs run in the expected order and are cleaned up. Any hook you intend to keep should be re-declared with an Argo CD annotation if you need to combine it with other Argo CD hooks, so the behavior is explicit.
Hook and value mistakes that break a migrated chart
Most failed Helm migrations into Argo CD trace back to a few assumptions carried over from helm install. Argo CD renders the chart, maps hooks to sync phases, merges values from several layers and names the release differently, so each assumption needs a check before the first sync.
Relying on Helm test hooks
Helm test hooks such as test-success do not run under Argo CD, and rollback hooks are ignored as well. A chart that depends on a test hook to gate a release will appear to pass while nothing verifies it. Before migrating, list every hook annotation in the chart templates and decide which checks belong in a PostSync Job or in your pipeline instead.
Mixing Helm and Argo CD hooks
Defining any Argo CD hook on a resource causes Argo CD to ignore all Helm hooks in the chart. A team that adds one PreSync annotation to a migration Job can silently lose the Helm pre-upgrade Job it depended on. Audit each chart for both hook families and convert them as a set, then confirm in a staging sync that each expected Job still runs.
Values set in two layers
Argo CD merges values from parameters, valuesObject, values, valueFiles and the chart's own values.yaml, with parameters winning. A value that appears in a values file and an inline override can look correct in Git while the rendered manifest uses the other one. Render the chart with the final Application spec, compare the output against the previous Helm release, and keep one owner for each key.
Changing the release name
The release name defaults to the Application name, so renaming an Application can change the names of rendered resources. Selectors, PersistentVolumeClaims and Service names derived from the release can then be recreated, which causes downtime or data loss on stateful workloads. Set the release name explicitly to match the existing Helm release, and review the diff for any Deployment, StatefulSet or PVC replacement before syncing.
Assuming helm list shows state
Argo CD uses Helm only to inflate the chart with helm template, so the release does not appear in helm list and no Helm release secret tracks its history. Teams that run helm status or helm rollback against a migrated release get confusing results. Move status checks to the Application view in Argo CD and document that rollback happens through Git, not through Helm.
Setting up a Helm chart deployment in Argo CD
This sequence moves a Helm chart from a manual helm install into an Argo CD Application that renders, syncs and tracks the release. Each step ends with a check so the team can confirm the chart behaves the same way before it reaches production clusters.
Inventory chart hooks and values
Before writing any Application, the platform team reads the chart's templates and values.yaml and lists every Helm hook annotation, such as pre-install, post-install, pre-upgrade and post-upgrade, along with its hook-weight and any test or rollback hooks. Argo CD ignores rollback and test hooks, and defining any Argo CD hook makes it ignore all Helm hooks, so this list shows what will change. The output is a short table of hooks and the values each template reads. Done when every hook has a planned Argo CD phase or a documented reason it will be dropped.
Choose the value sources and their order
The team decides where each value comes from: the chart's own values.yaml, one or more valueFiles in Git, an inline values block, a valuesObject, or parameters set on the Application. Argo CD applies parameters first, then valuesObject, values, valueFiles and finally the chart defaults, so the team should keep environment overrides in one layer and avoid setting the same key in several places. Done when each environment has a named value file or override and a reviewer can trace any final value to its source.
Define the Application with the chart source
The team writes the Application manifest with the chart repository URL, chart name, pinned target version, destination cluster and namespace, and the value sources chosen in the previous step. Pinning the chart version keeps renders reproducible, and the manifest is committed to the Git repository that holds Argo CD configuration. Done when the manifest passes a schema or dry-run check and the reviewer confirms the chart version is intended and not a floating default.
Set the release name explicitly
Argo CD uses the Application name as the Helm release name unless the team sets one. Because helm list will not show the release, the team should record the release name in the Application and confirm it matches the name used by any scripts, dashboards or existing resource labels from a previous helm install. Changing the release name later can recreate resources with new names, so the team should settle it before the first sync. Done when the chosen name is written in the manifest and recorded in the migration notes.
Register the chart repository with credentials in Secrets
The platform team registers the Helm repository or OCI registry with Argo CD by creating a Kubernetes Secret that holds the URL and read-only credentials, rather than adding it to the argocd-cm ConfigMap, because Argo CD 3.0 removed repository configuration from that ConfigMap. Access should use a dedicated read-only account and tokens scoped to the chart repository. Done when Argo CD lists the repository as connected in its settings and a test refresh of the Application succeeds without exposing the credential in logs or API responses.
Sync in a non-production cluster first
The team runs the first sync against a non-production cluster with manual sync, so each change is visible before it applies. They review the diff Argo CD shows, including the hook resources that will run in PreSync and PostSync phases, and confirm the sync wave order. Automated sync and prune should stay off until the first few syncs behave as expected. Done when the Application reports Synced and Healthy and the resources in the cluster match the diff the reviewer approved.
Verify rendered manifests and hook execution
The team compares the output of helm template run locally with the manifests Argo CD rendered, checking image tags, replica counts and the values that were supposed to win. They then confirm that each mapped hook ran in its expected phase by checking Job logs and status in the sync history, and that dropped hooks have no remaining effect. Done when the rendered output matches the local render, every hook job completed in the intended phase, and the results are saved as evidence for the change record.
Promote the same chart version to production
Once the non-production checks pass, the team promotes the same pinned chart version and value files to production through a reviewed Git change, rather than rebuilding values by hand. The production Application uses the same release name and hook mapping. The team should record what differs between environments, such as cluster-specific values, so the difference is documented. Done when the production Application shows the same rendered manifests as the approved non-production render, aside from the documented environment values.
Security and credentials for Helm sources
Helm charts are code that Argo CD executes on repository content, so the trust decision happens before the first sync. The cards below cover which charts and repositories to allow, where repository credentials belong, and what Argo CD hides from API responses and logs.
Limit which charts Argo CD renders
The repo-server runs Helm and Kustomize on the content of the repositories you connect. A chart can execute templating logic and read files the repo-server can reach, so an untrusted repository is a risk to the whole control plane, not just one application. Allow only known chart repositories and charts from a reviewed source, and check whether your Argo CD version lets you restrict source repositories per project before you add a new chart.
Keep out-of-tree file access in view
Helm value files and chart dependencies can reference paths that the repo-server reads from its own filesystem. Review every valueFiles entry and any chart that pulls in local files, because values that point outside the application path can expose content you did not intend to deploy. Ask your partner or your own team to confirm how the chosen Argo CD version limits these paths before enabling new sources.
Store repository credentials as Secrets
Since Argo CD 3.0, repositories are no longer configured in the argocd-cm ConfigMap, so repository URLs and their credentials must be defined as Kubernetes Secrets. Teams upgrading from 2.x that still keep repository entries in the ConfigMap will find them missing after the move. Confirm during upgrade planning that every Helm repository, including private OCI or chart registries, has a Secret with its own access scope.
Use a read-only chart credential
A Helm repository credential only needs to fetch charts, so it should not carry write access to the Git or registry it sits beside. Give each chart source its own credential, rotate it through your normal secret process, and avoid reusing a personal token. Record which Application uses which repository so that revoking one credential does not break unrelated deployments.
Confirm redaction in your own logs
Argo CD redacts cluster, Git and OAuth2 credentials from API responses and logs. That protects the Argo CD surface, but it does not cover values you place in Helm value files, which are stored in Git and visible in the rendered manifests. Check your log pipeline and the Application diff view with a test secret before you rely on redaction for anything sensitive.
Protect the API with JSON Web Tokens
Argo CD authenticates API requests only with JSON Web Tokens and uses TLS for traffic between its components. Your Helm workflow depends on this when automation fetches Application state or triggers syncs. Decide who may create tokens for CI systems, set expiry according to your policy, and confirm that the API endpoint is reachable only from networks that need it.
Questions teams ask before moving Helm releases to Argo CD
What drives the effort of moving Helm releases to Argo CD?
The effort follows the inventory: how many releases you run, how each chart is configured and how much the current process depends on hooks and ordering. Each Helm release needs an Argo CD Application, a chart source, a value strategy and a release name that matches what already exists in the cluster. Charts with several value files, hooks that run database migrations or jobs that must run in a set order add review and test time, because each one must be mapped to sync phases and waves and verified. Releases deployed from CI pipelines also need those pipelines removed or redirected, so two systems do not change the same resources. Ask a partner to build the quote from a written inventory of releases, hooks and value sources, and confirm the scope in writing before work starts.
Can our own team move Helm releases to Argo CD without a partner?
Yes, many teams can do it themselves, particularly when they have a small number of stateless charts and already run Kubernetes and Git-based workflows. The mechanics are documented: Argo CD renders the chart with helm template, applies the output and tracks the resulting resources. Start with one non-critical release in a test cluster. Teams most often struggle with value precedence, hook behavior and repository credentials, because a small change in any of them alters what reaches the cluster. If you keep the work in-house, run a pilot, compare the rendered manifests with what helm install produced, and write a runbook before the first production cutover. DeployOpen plans, implements and documents this work under a fixed scope, or it can work alongside your team. The right choice depends on your staffing, your change windows and how many releases must move.
What does a Helm to Argo CD migration need from our team?
Your team needs to name an owner for each release, grant access to the Git repositories that hold charts and value files, and provide access to the destination clusters. Engineers who know each chart must review the rendered output, because that output is what Argo CD applies. Security or platform staff need to approve how repository credentials are stored, since Argo CD 3.0 removed repository configuration from the argocd-cm ConfigMap and repositories are now defined as Kubernetes Secrets. Expect time from people who can answer questions about hooks, secrets and dependencies between releases, and schedule change windows for each cutover. Ask your partner to list these inputs in the scope document so dependencies are visible before the timeline is set.
How long does a migration take for our chart count and hooks?
No duration can be given for this work from the available research, so the schedule should follow the inventory. The main drivers are the number of releases, the number of value sources each one uses, whether charts depend on each other, how many hooks must be mapped to PreSync, PostSync and sync waves, and how many clusters receive each release. Stateful releases such as databases need a cutover plan and a rehearsal, which lengthens the schedule. Releases that only add a Deployment and a Service usually move faster. A useful check is whether each rendered manifest can be reproduced in a non-production cluster before production. Ask for a timeline that lists each release group, its dependencies and the environments where it will be verified, and treat any single figure as provisional until that inventory exists.
Does helm rollback still work after moving releases to Argo CD?
Helm rollback does not apply to a release once Argo CD manages its lifecycle. Argo CD tracks the desired state in Git and syncs the cluster to it, so a rollback is normally a Git change that restores an earlier chart version or set of values, which Argo CD then syncs. Argo CD can also sync an application to an earlier revision from its own interface or API. Confirm the exact rollback options for your Argo CD version in the Helm guide and the upgrade notes before you depend on them. Whichever method you choose, practice it on a non-production release, because automated sync and self-heal change how quickly a manual change is reverted. Keeping value files and chart versions in Git gives you a reviewable record of what was deployed.
Why does helm list no longer show our releases after migration?
Argo CD uses Helm only to inflate charts with helm template, and Argo CD, not Helm, manages the release lifecycle. As a result, helm list does not show releases that Argo CD manages, and engineers who check that command during an incident may think a release has disappeared. Update runbooks, dashboards and on-call notes so people check the Application in Argo CD, its sync status and the health of the resources it manages. Tell anyone who uses Helm commands during incidents where release state now lives. Keep the Application definitions in Git so they can be reviewed and restored. Review the Argo CD FAQ and confirm with your tooling owners which scripts or reports depend on Helm release data.
Do Helm hooks still run after moving to Argo CD?
Hooks are carried over as Argo CD sync phases and waves, and the mapping is specific. Helm pre-install and pre-upgrade hooks become PreSync, post-install and post-upgrade hooks become PostSync, and hook-weight becomes a sync wave. Rollback and test hooks are ignored. Defining any Argo CD hook makes Argo CD ignore all Helm hooks, so a chart that mixes both needs deliberate review. A test hook that you still want needs a replacement, such as a PostSync job. Check that jobs have cleanup or deletion policies so they do not accumulate between syncs, and look for hooks that assume Helm's rollback behavior. Confirm the mapping for each chart in the Helm guide, then run every hook once in a non-production cluster before production.
How should we handle repository credentials for private Helm charts?
Argo CD needs read access to each private chart repository, and you define that access as a Kubernetes Secret. Since Argo CD 3.0, repository configuration is no longer read from the argocd-cm ConfigMap, so any setup that stored repository details there must move to Secrets before the upgrade. Use a read-only deploy key or token scoped to the chart repository, and keep it out of value files and Git history. Restrict who can read Secrets in the Argo CD namespace, because the repo-server runs Helm on repository content and that content can be untrusted. Plan credential rotation as an operational task, and confirm the exact Secret labels and fields for your version in the upgrade notes before you change anything.
How DeployOpen scopes and delivers Argo CD Helm deployments
DeployOpen plans and implements Helm chart deployments through Argo CD inside infrastructure you control. We map each chart's hooks, value files and release names to Argo CD behavior before anything is synced, so the written scope reflects how your charts will actually run.
How we scope
- Inventory every chart, its dependencies, and the hooks it defines before agreeing on the deployment design.
- Record value file precedence and which inputs come from parameters, valuesObject, or external value files.
- Confirm the release name convention per Application and the repository credentials Argo CD will use to pull charts.
How we build
- Render each chart with helm template and review the output to confirm the manifests Argo CD will apply.
- Translate pre-install, post-install and hook-weight definitions into PreSync, PostSync and sync wave settings, and test the ordering.
- Store repository credentials as Kubernetes Secrets and verify Helm and Kustomize rendering runs only on repositories you trust.
How we hand over
- Deliver a written record of the value precedence model, release naming rules and hook mapping for each application.
- Document the sync verification steps your team runs after each chart version change, with expected results.
- Walk your platform team through troubleshooting, including the fact that helm list will not show Argo CD-managed releases.
How we support
- Engagements are fixed-scope, with scope, deliverables and timelines agreed in writing before work starts.
- Ongoing support, chart upgrades and continuous testing are available as a retainer after handover.
- Ask any partner for a quote built from your written scope, including what is one-time setup and what recurs.
