Skip to main content
Cloud DevOps Solutions
Get a quote Talk to an engineer
Infrastructure as Code 2026-11-12 18 min read

What Is ArgoCD? The Complete Guide to GitOps Deployments

Saddique Khan

DevOps / SRE Engineer & CEO, Cloud DevOps Solutions

ArgoCD is an open-source, declarative, GitOps continuous delivery tool for Kubernetes. It watches a Git repository for changes to Kubernetes manifests and automatically synchronises the live cluster state with what is declared in Git. No more kubectl apply from a CI pipeline, no more manual hotfixes that drift from what the team agreed on.

With over 18,000 GitHub stars and adoption by companies running thousands of clusters, ArgoCD has become the default choice for teams that want Git to be the single source of truth for their Kubernetes deployments.

This guide explains what ArgoCD is, how its architecture works, what problems it solves, and how to run it in production. If you want a hands-on walkthrough instead, see our ArgoCD on EKS tutorial.

Why ArgoCD exists

Before GitOps tools like ArgoCD, most teams deployed to Kubernetes from CI pipelines. A typical flow: CI builds the image, pushes it to a registry, then runs kubectl apply or helm upgrade against the cluster. This works until it doesn’t:

  • Drift: Someone runs a kubectl edit in production. The cluster state no longer matches what is in Git. Nobody notices until the next deploy overwrites the change, or worse, the change causes an incident.
  • No audit trail: CI pipeline logs show that a deploy happened, but not what changed in the cluster. Rollback means rerunning an older pipeline, hoping the state is reproducible.
  • Credential sprawl: Every CI runner needs cluster credentials. That is a wide attack surface: one compromised pipeline can modify any namespace it has access to.
  • No continuous reconciliation: If someone deletes a ConfigMap manually, the cluster stays broken until the next pipeline run.

ArgoCD solves all four. It sits inside the cluster, pulls changes from Git (instead of CI pushing changes to the cluster), and continuously reconciles actual state with desired state.

How ArgoCD works: architecture

ArgoCD runs as a set of controllers inside the Kubernetes cluster. The main components:

API Server

The ArgoCD API server handles the web UI, CLI commands, and the gRPC/REST API. It authenticates users, enforces RBAC, and exposes operations like sync, rollback, and app creation.

Repository Server

The repo server clones Git repositories, renders Helm charts, processes Kustomize overlays, and generates plain Kubernetes manifests. It caches repository state so that polling is efficient even across hundreds of applications.

Application Controller

The controller is the core reconciliation loop. It compares the desired state (manifests from Git, rendered by the repo server) with the live state (what is actually running in the cluster). When it detects a difference, it either:

  • Reports the drift (manual sync mode), or
  • Automatically applies the change (auto-sync mode)

Redis

Used for caching and as a lightweight message bus between components.

Dex / OIDC

ArgoCD integrates with identity providers for single sign-on. Dex is bundled by default, but you can point directly at any OIDC provider (Okta, Azure AD, Google Workspace).

The pull-based model is the key architectural difference from CI-driven deploys. ArgoCD pulls from Git; CI never needs cluster credentials.

Core concepts

Application

An Application is the central resource in ArgoCD. It defines:

  • Source: a Git repository, branch/tag, and path within the repo (or a Helm chart repository and chart name)
  • Destination: a Kubernetes cluster and namespace
  • Sync policy: manual or automatic, with optional self-heal and prune
apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: payment-service
  namespace: argocd
spec:
  project: production
  source:
    repoURL: https://github.com/acme/k8s-manifests
    targetRevision: main
    path: apps/payment-service/production
  destination:
    server: https://kubernetes.default.svc
    namespace: production
  syncPolicy:
    automated:
      prune: true
      selfHeal: true
    syncOptions:
      - CreateNamespace=true

Project

Projects group Applications and enforce guardrails: which repositories are allowed, which clusters and namespaces are permitted, and which Kubernetes resource types can be deployed. The default project has no restrictions; production setups should define stricter projects.

Sync

A sync operation takes the desired state from Git and applies it to the cluster. ArgoCD supports:

  • Manual sync: a human (or automation) triggers the sync from the UI or CLI
  • Auto-sync: ArgoCD detects a Git change and syncs automatically, typically within 3 minutes (the default polling interval)

Sync waves and hooks

For complex deployments where resources must be applied in order (namespace first, then CRDs, then deployments), ArgoCD supports sync waves (numeric ordering) and resource hooks (PreSync, Sync, PostSync, SyncFail). A database migration Job might run as a PreSync hook before the new application version deploys.

Health status

ArgoCD checks the health of every resource it manages. A Deployment is healthy when its rollout completes. A Service is healthy when it has endpoints. Custom health checks can be defined in Lua for CRDs and other resource types.

ArgoCD with different manifest formats

ArgoCD is not limited to plain YAML. It supports:

FormatHow it works
Plain Kubernetes YAMLApplied directly
Helm chartsRendered with configurable values files and parameters
KustomizeProcessed with overlays, patches, and image transformers
JsonnetRendered to Kubernetes manifests
Config management pluginsCustom tools (e.g. cdk8s, Pulumi Kubernetes) via plugin interface

This flexibility matters because teams rarely standardise on one format across all applications. ArgoCD handles mixed repositories without any extra tooling.

ApplicationSets: managing multiple environments

Real-world Kubernetes setups have multiple environments (dev, staging, production) and often multiple clusters. Creating one Application resource per environment per service is tedious and error-prone.

ApplicationSets solve this with generators. You define a template and a generator that produces parameters:

apiVersion: argoproj.io/v1alpha1
kind: ApplicationSet
metadata:
  name: payment-service
  namespace: argocd
spec:
  generators:
    - list:
        elements:
          - cluster: dev
            url: https://dev-cluster.example.com
            namespace: dev
          - cluster: staging
            url: https://staging-cluster.example.com
            namespace: staging
          - cluster: production
            url: https://prod-cluster.example.com
            namespace: production
  template:
    metadata:
      name: 'payment-service-{{cluster}}'
    spec:
      project: '{{cluster}}'
      source:
        repoURL: https://github.com/acme/k8s-manifests
        targetRevision: main
        path: 'apps/payment-service/{{cluster}}'
      destination:
        server: '{{url}}'
        namespace: '{{namespace}}'

Other generators include Git directory (one Application per directory in a monorepo), Git file (parameters from JSON files in Git), cluster (one Application per registered cluster), and merge (combine multiple generators).

ArgoCD vs Flux: which GitOps tool to choose

Both ArgoCD and Flux are CNCF graduated projects that implement GitOps for Kubernetes. The choice depends on your priorities:

DimensionArgoCDFlux
UIFull web UI with visualisation, diffs, logs, and sync controlsNo built-in UI (third-party options like Weave GitOps)
ArchitectureCentralised controller with API serverDistributed toolkit of controllers (source, kustomize, helm, notification)
Multi-tenancyProjects with RBAC, SSO, audit logsTenancy via namespaced resources and Kubernetes RBAC
Multi-clusterFirst-class support: register external clusters, manage from one control planeSupports multi-cluster but typically one Flux instance per cluster
Helm supportRenders Helm in the repo server; treats the output as plain manifestsNative HelmRelease CRD with drift detection and remediation
Learning curveSteeper initial setup, but the UI makes day-2 operations easierSimpler initial setup, CLI-first workflow
NotificationsBuilt-in notification controller (Slack, Teams, webhooks, GitHub)Separate notification controller, similar integrations

Our recommendation: ArgoCD works better for teams that need a UI for visibility, manage multiple clusters from a central point, or have strict RBAC and audit requirements. Flux is a good fit for teams that prefer a lightweight, CLI-driven approach and manage clusters independently. See our ArgoCD vs Flux comparison for a deeper analysis.

ArgoCD with GitHub

Most teams store Kubernetes manifests in GitHub. ArgoCD integrates with GitHub in several ways:

Repository connection

ArgoCD connects to GitHub repositories via HTTPS (with a personal access token or GitHub App) or SSH (with a deploy key). For organisations with many repositories, a GitHub App provides centralised access control without per-repo deploy keys.

Webhook-driven sync

By default, ArgoCD polls Git every 3 minutes. For faster deploys, configure a GitHub webhook that notifies ArgoCD on push events. This brings sync latency down to seconds.

Commit status

ArgoCD can report sync status back to GitHub as a commit status check. Pull requests show whether the manifests they change are successfully synced, providing a feedback loop before merging.

GitHub SSO

ArgoCD supports GitHub as an OIDC provider for single sign-on. Team membership in GitHub maps to RBAC roles in ArgoCD, so access control follows the same model developers already use.

Production best practices

Keep application manifests in a separate repository

Do not put Kubernetes manifests in the same repository as application source code. Use a dedicated “k8s-manifests” or “gitops-config” repository. This separation means:

  • CI updates an image tag in the manifests repo after a successful build
  • ArgoCD syncs from the manifests repo
  • Application developers and platform engineers have separate review workflows

Enable auto-sync with self-heal and prune

For production clusters, enable all three:

syncPolicy:
  automated:
    prune: true      # delete resources removed from Git
    selfHeal: true   # revert manual changes in the cluster

Without prune, deleting a manifest from Git leaves the resource running. Without selfHeal, manual kubectl changes persist until the next Git change triggers a sync.

Use Projects for isolation

Define ArgoCD Projects per team or environment. Restrict which repositories, clusters, namespaces, and resource types each project can use. This prevents a development team from accidentally deploying to the production namespace.

Secure the repo server

The repo server clones and processes Git repositories. In a multi-tenant setup, a malicious Helm chart or Jsonnet file could attempt to read secrets from the repo server’s filesystem. Mitigations:

  • Run the repo server with a read-only filesystem
  • Set resource limits to prevent resource exhaustion
  • Use network policies to restrict egress from the repo server pod

Enable notifications

Configure the ArgoCD notifications controller to send alerts on sync failures, health degradation, and successful deployments. Slack, Microsoft Teams, email, and generic webhooks are all supported. A failed sync should page the on-call engineer, not sit unnoticed in the UI.

Monitor ArgoCD itself

ArgoCD exposes Prometheus metrics on each component. Key metrics to watch:

  • argocd_app_info with labels for sync status and health status
  • argocd_app_sync_total for sync frequency
  • argocd_app_reconcile_count for controller workload
  • argocd_repo_server_request_duration for repo server latency

Set up Grafana dashboards and alerts so you know when ArgoCD itself is unhealthy. See our Prometheus and Grafana monitoring guide for dashboard setup.

Plan for disaster recovery

ArgoCD stores its configuration (Applications, Projects, repository credentials, cluster secrets) in Kubernetes resources within the argocd namespace. Back up these resources regularly. Since the actual application manifests live in Git, losing ArgoCD is recoverable: reinstall ArgoCD, restore the backup, and it reconciles everything from Git.

For critical setups, run ArgoCD in HA mode with multiple replicas of the application controller and API server.

Common ArgoCD deployment patterns

Pattern 1: App of Apps

A parent Application points to a directory of Application manifests. Adding a new microservice means adding one YAML file to Git; the parent Application picks it up automatically. This scales well for teams managing dozens of services.

Pattern 2: ApplicationSet with Git directory generator

Point an ApplicationSet at a monorepo directory structure. Each subdirectory becomes an Application. No need to maintain a separate list of applications.

Pattern 3: Hub-and-spoke multi-cluster

A central “management” cluster runs ArgoCD and manages workload clusters. The management cluster registers each workload cluster via argocd cluster add. Applications specify which cluster to deploy to. Platform teams get a single pane of glass; workload clusters do not run ArgoCD.

Pattern 4: Progressive delivery with Argo Rollouts

Combine ArgoCD with Argo Rollouts for canary and blue-green deployments. ArgoCD manages the desired state; Rollouts controls how the new version is gradually promoted based on metrics from Prometheus, Datadog, or other providers.

When to use ArgoCD

ArgoCD is the right choice when:

  • You run Kubernetes and want Git as the source of truth for cluster state
  • You need a UI for developers and platform engineers to see what is deployed where
  • You manage multiple clusters and want centralised visibility
  • You have compliance or audit requirements that demand a full history of every change
  • You want to eliminate direct cluster access from CI pipelines

ArgoCD is not the right tool for non-Kubernetes workloads (use Terraform, Ansible, or a general-purpose CD tool), for teams that do not use Git (rare, but it happens), or for ephemeral development environments where reconciliation overhead is not worthwhile.

Getting started

  1. Install ArgoCD in your Kubernetes cluster (see our step-by-step EKS tutorial)
  2. Connect a Git repository with your Kubernetes manifests
  3. Create an Application pointing to that repository
  4. Verify the sync in the ArgoCD UI or CLI
  5. Enable auto-sync once you trust the workflow

For teams that want help designing a GitOps architecture with ArgoCD, from repository structure to multi-cluster strategy to RBAC policies, we offer GitOps consulting as part of our DevOps practice.

Key takeaways

  • ArgoCD is a Kubernetes-native GitOps tool that continuously reconciles cluster state with Git
  • Its pull-based model eliminates the need for CI pipelines to hold cluster credentials
  • ApplicationSets and the App of Apps pattern scale to hundreds of applications across multiple clusters
  • The built-in UI, RBAC, SSO, and audit logging make it suitable for production and compliance-sensitive environments
  • ArgoCD and Flux are both mature choices; ArgoCD is stronger on UI and multi-cluster, Flux on lightweight single-cluster setups
  • Production setups should enable auto-sync with self-heal and prune, enforce Projects for isolation, and monitor ArgoCD with Prometheus

Need help setting up ArgoCD or designing a GitOps strategy for your Kubernetes clusters? Book a free consultation and we will review your deployment workflow.

#argocd #gitops #kubernetes #ci-cd #flux

Related service

Need hands-on help? Our certified engineers deliver this as a managed service.

GitOps with Helm, ArgoCD & Flux
Found this useful? Share it with your team or link to it from your documentation.

Need help implementing this?

Our certified engineers can handle the setup, migration, or ongoing operations for you.