How to Use Argo CD with Helm Charts: A Complete GitOps Guide

Argo CD treats Helm charts as templating engines by running helm template internally and managing the resulting Kubernetes manifests declaratively, eliminating the need for Helm release objects in the cluster while enabling full GitOps workflows for chart-based applications.

Argo CD from the argoproj/argo-cd repository provides native first-class support for Helm charts, allowing teams to deploy Kubernetes applications using Helm's templating capabilities without relying on the Helm client for lifecycle management. This integration enables you to store chart configurations, version pinning, and custom values entirely in Git, letting Argo CD handle the rendering and synchronization to your clusters. Understanding how Argo CD processes Helm charts—as opposed to traditional Helm installations—is essential for implementing secure, reproducible GitOps pipelines.

How Argo CD Processes Helm Charts

Unlike traditional Helm workflows that execute helm install or helm upgrade, Argo CD invokes helm template to render charts into raw Kubernetes manifests. According to the source code in util/helm/helm.go, the rendering logic processes the chart locally, applies values files and parameters, and outputs the generated manifests. Argo CD then tracks these resources using its own sync engine, creating no Helm release secrets or metadata in the cluster. This approach means you cannot use native Helm commands like helm list or helm rollback against Argo CD-managed applications; instead, you rely on Argo CD's declarative state management and rollback capabilities.

Defining a Helm-Based Application

The Application Custom Resource (CR) defines how Argo CD interacts with Helm charts. The structure is defined in pkg/apis/application/v1alpha1/types.go, specifically within the ApplicationSourceHelm struct. This specification supports public Helm repositories, private Git repositories, and OCI registries.

Basic Helm Chart Configuration

To deploy a Helm chart from a standard repository, specify the repoURL, chart name, and targetRevision in your Application manifest:

apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: sealed-secrets
  namespace: argocd
spec:
  project: default
  source:
    repoURL: https://bitnami-labs.github.io/sealed-secrets
    chart: sealed-secrets
    targetRevision: 1.16.1
    helm:
      releaseName: sealed-secrets
  destination:
    server: "https://kubernetes.default.svc"
    namespace: kubeseal

The helm.releaseName field sets the Helm release name, which affects resource naming and labeling within the target namespace.

OCI Registry Support

Argo CD supports Helm charts stored in OCI registries (such as Amazon ECR, Google Artifact Registry, or Docker Hub) without requiring the oci:// prefix. As documented in docs/user-guide/helm.md, specify the OCI endpoint directly in repoURL:

apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: nginx
  namespace: argocd
spec:
  project: default
  source:
    repoURL: registry-1.docker.io/bitnamicharts
    chart: nginx
    targetRevision: 15.9.0
  destination:
    name: "in-cluster"
    namespace: nginx

Managing Values and Configuration Precedence

Argo CD provides multiple mechanisms for supplying values to Helm charts, with a strict precedence order defined in the source code. When values are merged, the hierarchy is: parameters > valuesObject > values > valueFiles > repository values.yaml.

Using Value Files

Specify multiple value files using the valueFiles array under the helm stanza. You can also use glob patterns and set ignoreMissingValueFiles: true to prevent failures when optional files are absent:

spec:
  source:
    helm:
      valueFiles:
        - values-production.yaml
        - values-common.yaml
        - values-optional-override.yaml
      ignoreMissingValueFiles: true

Inline Values and Parameters

For immediate overrides, use the values field for inline YAML or parameters for individual --set equivalents. You can also update existing applications via the CLI:

argocd app set helm-guestbook --values values-production.yaml

Multiple Sources for Advanced Workflows

Since version 2.6, Argo CD supports the multiple sources feature, allowing you to store Helm charts and values files in separate Git repositories. This decouples the application code from configuration data, enabling teams to maintain a single chart while managing environment-specific values in distinct repositories with different access controls.

Configuring Helm Options in Argo CD

Server-side Helm behavior is controlled through settings defined in util/settings/settings.go. This includes configuration for allowed value file schemes, Helm binary paths, and security constraints. Review these settings when running Argo CD in restricted environments or when integrating with private certificate authorities.

Summary

• Argo CD renders Helm charts using helm template in util/helm/helm.go, managing the output directly without creating Helm release objects in the cluster.
• Define Helm applications using the ApplicationSourceHelm struct in pkg/apis/application/v1alpha1/types.go, supporting standard repos, Git, and OCI registries.
• Value precedence follows a strict hierarchy: parameters > valuesObject > values > valueFiles > repository defaults.
• OCI-based charts are supported natively using registry URLs without the oci:// protocol prefix.
• Multiple sources (v2.6+) allow separating chart repositories from values file repositories for flexible configuration management.

Frequently Asked Questions

Does Argo CD create Helm release secrets in the cluster?

No. Argo CD runs helm template locally and manages the rendered manifests directly through its own tracking mechanisms. No Helm release secrets or release objects are created in the cluster, which means you cannot use helm list or helm rollback against Argo CD-managed applications.

How do I pass custom values to a Helm chart in Argo CD?

You can supply values through multiple mechanisms in the Application spec: valueFiles for external files, values for inline YAML, valuesObject for structured data, or parameters for individual --set overrides. The CLI command argocd app set <app> --values <file> also updates existing applications dynamically.

Can I use Helm charts stored in OCI registries like Amazon ECR or Docker Hub?

Yes. Argo CD supports OCI-based Helm charts. Specify the registry URL in repoURL (e.g., registry-1.docker.io/bitnamicharts) without the oci:// prefix, and Argo CD will pull and template the chart directly from the OCI registry as implemented in the codebase.

What is the difference between Argo CD's Helm support and running Helm manually?

Traditional Helm installs execute client-side logic that creates release metadata and secrets in the cluster. Argo CD instead treats Helm purely as a templating engine, rendering manifests with helm template and then applying them using its own GitOps reconciliation loop, providing drift detection, automated sync, and rollback capabilities that standard Helm cannot.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}