Argo CD GitOps Approach: Declarative Continuous Delivery for Kubernetes

Argo CD implements a pure GitOps workflow where Git repositories serve as the single source of truth for Kubernetes infrastructure, automatically reconciling live cluster state with desired state through continuous reconciliation loops.

Argo CD's GitOps approach transforms how teams deploy to Kubernetes by treating version-controlled repositories as the canonical configuration source. According to the argoproj/argo-cd repository, this declarative continuous delivery tool continuously monitors Git repositories and synchronizes cluster resources without manual intervention, ensuring that the actual state always matches the committed configuration.

Declarative Source of Truth in Git

At the core of Argo CD's GitOps approach is the principle that Git is the single source of truth. All Kubernetes manifests—including plain YAML, Kustomize overlays, Helm charts, Jsonnet, and OCI artifacts—are stored in version control. Argo CD reads these manifests directly from Git (or remote OCI images) and refuses to honor manual cluster changes that bypass the repository.

As stated in the repository's README.md, Argo CD is explicitly designed as a "declarative GitOps continuous delivery tool" for Kubernetes. This means the desired state of an entire cluster or application set is defined declaratively in files, not in imperative scripts or manual console commands.

The Application CRD: Defining Desired State

Argo CD introduces an Application custom resource (CRD) that bridges Git repositories to Kubernetes clusters. Defined in pkg/apis/application/v1alpha1/types.go, this resource specifies exactly where to fetch manifests and where to deploy them.

Each Application represents a logical unit of delivery, pointing to a specific Git repository, revision, path, and destination cluster or namespace. The Argo CD controller watches these Application objects and the referenced Git repositories for changes, triggering synchronizations when drift is detected.

Here is a declarative Application manifest that embodies the GitOps approach:

apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: guestbook
spec:
  project: default
  source:
    repoURL: https://github.com/argoproj/argocd-example-apps.git
    targetRevision: HEAD
    path: guestbook
  destination:
    server: https://kubernetes.default.svc
    namespace: guestbook
  syncPolicy:
    automated:
      prune: true          # Delete resources no longer defined in Git

      selfHeal: true       # Sync if drift is detected

Continuous Reconciliation via the GitOps Engine

The reconciliation logic in Argo CD's GitOps approach lives in the reusable GitOps Engine library. Located in the gitops-engine/ directory, this engine parses manifests, computes diffs between desired state (from Git) and live cluster state, and produces sync plans.

In controller/state.go, the application-controller implements the core sync loop. It periodically polls Git repositories or receives webhook notifications, then automatically corrects any out-of-sync resources. This continuous reconciliation ensures that:

• Automated sync: Changes merged to Git automatically deploy to the cluster
• Self-healing: Manual cluster modifications are reverted to match the Git-defined state
• Pruning: Resources deleted from Git are automatically removed from the cluster

You can also trigger manual synchronizations via CLI when needed:

# Create the application from Git

argocd app create guestbook \
  --repo https://github.com/argoproj/argocd-example-apps.git \
  --path guestbook \
  --dest-server https://kubernetes.default.svc \
  --dest-namespace guestbook \
  --sync-policy automated

# Force immediate synchronization

argocd app sync guestbook

Declarative Tooling Integration

Argo CD's GitOps approach natively supports templating tools, ensuring that even rendered manifests maintain traceability to version-controlled sources. The controller hydrates templates on-the-fly for:

• Kustomize: Overlays and patches stored in Git
• Helm: Charts and value files as configuration source
• Jsonnet: Template-based configuration generation
• OCI: Artifacts stored in container registries

As documented in docs/user-guide/kustomize.md, these integrations ensure that the rendered manifests are produced deterministically from the Git-backed configuration, maintaining the GitOps guarantee that what is in the repository is what runs in the cluster.

Multi-Cluster GitOps at Scale with ApplicationSet

For enterprise-scale deployments, the ApplicationSet controller extends the Argo CD GitOps approach to multi-tenant and multi-cluster scenarios. Defined in docs/operator-manual/applicationset/index.md, this resource generates multiple Application objects from a single declarative definition.

ApplicationSets support generators for cluster lists, Git repository discovery, and pull-request workflows, allowing teams to manage hundreds of clusters while keeping the source of truth in Git:

apiVersion: argoproj.io/v1alpha1
kind: ApplicationSet
metadata:
  name: guestbook-multi-cluster
spec:
  generators:
  - list:
      elements:
      - cluster: dev
        url: https://dev-cluster.example.com
      - cluster: prod
        url: https://prod-cluster.example.com
  template:
    metadata:
      name: '{{cluster}}-guestbook'
    spec:
      project: default
      source:
        repoURL: https://github.com/argoproj/argocd-example-apps.git
        targetRevision: HEAD
        path: guestbook
      destination:
        server: '{{url}}'
        namespace: guestbook
      syncPolicy:
        automated:
          prune: true

Security and Auditability

Because every change passes through Git, Argo CD's GitOps approach provides natural audit trails through commit history. As documented in docs/operator-manual/security.md, the platform respects Git-based RBAC (push permissions) and integrates with external secret stores to prevent sensitive data from being committed to version control.

This architecture ensures that:

• All changes are traceable to specific commits and authors
• Rollbacks are performed by reverting Git commits
• Secret rotation is handled outside of Git via integration with tools like External Secrets Operator

Summary

• Git as source of truth: Argo CD treats Git repositories as the canonical configuration store, supporting YAML, Helm, Kustomize, and OCI artifacts.
• Application CRD: The Application resource in pkg/apis/application/v1alpha1/types.go declaratively defines the relationship between Git repos and target clusters.
• Continuous reconciliation: The GitOps Engine and controller/state.go continuously poll Git and auto-correct cluster drift.
• Scalable GitOps: ApplicationSets extend the model to multi-cluster deployments while maintaining Git as the single source of truth.
• Auditability: Immutable Git history provides complete audit trails for compliance and rollback scenarios.

Frequently Asked Questions

What is the difference between Argo CD's GitOps approach and traditional CI/CD?

Traditional CI/CD pipelines typically push changes to clusters using imperative commands or scripts, often requiring credentials inside the CI system. Argo CD's GitOps approach inverts this model: agents inside the cluster pull configurations from Git, eliminating the need to expose cluster credentials externally. This pull-based model, implemented in controller/state.go, ensures that the cluster continuously reconciles itself against the desired state defined in version control.

How does Argo CD handle configuration drift?

Argo CD detects drift through the GitOps Engine's diff calculation logic, comparing live cluster state against the desired state stored in Git. When selfHeal: true is configured in the syncPolicy, the controller automatically reverts unauthorized manual changes to restore the Git-defined configuration. This enforcement happens in the reconciliation loop defined in controller/state.go, typically running every few minutes or triggered by webhooks.

Can Argo CD deploy to multiple clusters using the same GitOps workflow?

Yes, through the ApplicationSet controller. Instead of managing individual Application resources for each cluster, ApplicationSets use generators to create multiple applications from a single template. As documented in docs/operator-manual/applicationset/index.md, this supports list-based generators for specific clusters, Git generators for monorepos, and PR generators for preview environments—all while maintaining Git as the single source of truth.

What repository formats does Argo CD support for GitOps deployments?

Argo CD supports plain YAML, Kustomize overlays, Helm charts (including value files), Jsonnet, and OCI artifacts. The controller hydrates these formats on-the-fly before applying them to the cluster, ensuring that even templated configurations remain traceable to specific Git commits. This support is implemented across the codebase with specific handlers in the repository server and documented in docs/user-guide/application_sources.md.

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