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

> Master Argo CD with Helm charts using this complete GitOps guide. Learn how Argo CD manages chart templating declaratively for seamless Kubernetes application deployments.

- Repository: [Argo Project/argo-cd](https://github.com/argoproj/argo-cd)
- Tags: how-to-guide
- Published: 2026-07-09

---

**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`](https://github.com/argoproj/argo-cd/blob/main/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`](https://github.com/argoproj/argo-cd/blob/main/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:

```yaml
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`](https://github.com/argoproj/argo-cd/blob/main/docs/user-guide/helm.md), specify the OCI endpoint directly in `repoURL`:

```yaml
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:

```yaml
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:

```bash
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`](https://github.com/argoproj/argo-cd/blob/main/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`](https://github.com/argoproj/argo-cd/blob/main/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`](https://github.com/argoproj/argo-cd/blob/main/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.