What Is ArgoCD? The Complete Guide to GitOps Deployments
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 editin 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:
| Format | How it works |
|---|---|
| Plain Kubernetes YAML | Applied directly |
| Helm charts | Rendered with configurable values files and parameters |
| Kustomize | Processed with overlays, patches, and image transformers |
| Jsonnet | Rendered to Kubernetes manifests |
| Config management plugins | Custom 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:
| Dimension | ArgoCD | Flux |
|---|---|---|
| UI | Full web UI with visualisation, diffs, logs, and sync controls | No built-in UI (third-party options like Weave GitOps) |
| Architecture | Centralised controller with API server | Distributed toolkit of controllers (source, kustomize, helm, notification) |
| Multi-tenancy | Projects with RBAC, SSO, audit logs | Tenancy via namespaced resources and Kubernetes RBAC |
| Multi-cluster | First-class support: register external clusters, manage from one control plane | Supports multi-cluster but typically one Flux instance per cluster |
| Helm support | Renders Helm in the repo server; treats the output as plain manifests | Native HelmRelease CRD with drift detection and remediation |
| Learning curve | Steeper initial setup, but the UI makes day-2 operations easier | Simpler initial setup, CLI-first workflow |
| Notifications | Built-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_infowith labels for sync status and health statusargocd_app_sync_totalfor sync frequencyargocd_app_reconcile_countfor controller workloadargocd_repo_server_request_durationfor 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
- Install ArgoCD in your Kubernetes cluster (see our step-by-step EKS tutorial)
- Connect a Git repository with your Kubernetes manifests
- Create an Application pointing to that repository
- Verify the sync in the ArgoCD UI or CLI
- 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.
Related service
Need hands-on help? Our certified engineers deliver this as a managed service.
GitOps with Helm, ArgoCD & Flux