Argo CD: GitOps continuous delivery for Kubernetes

What Argo CD is

Argo CD is a declarative GitOps continuous delivery tool for Kubernetes. Its documentation states the two ideas behind it plainly: application definitions, configurations and environments should be declarative and version controlled, and application deployment and lifecycle management should be automated, auditable and easy to understand. In practice that means a Git repository holds the desired state of every application, and Argo CD runs inside the cluster, continuously comparing what Git says should exist with what is actually running, then reporting and correcting the difference.

The project targets platform teams that run Kubernetes for several application teams, and smaller teams that want deployments to happen through pull requests rather than through scripts with cluster credentials. Because the deploy step becomes "merge a change to Git", the CI system no longer needs direct access to the cluster or to the Argo CD API server: the automated sync documentation points out that a pipeline can simply commit and push manifest changes to the tracked repository, and Argo CD picks them up.

Argo CD is written in Go, licensed under Apache-2.0 and developed in the open on GitHub under the argoproj organisation. Participation is governed by the CNCF Code of Conduct, and the repository links to an official list of organisations that have adopted it. The README badges also reference SLSA level 3 for releases, the OpenSSF Best Practices programme and an OpenSSF Scorecard.

How it works

The GitOps loop

Argo CD follows the GitOps pattern of using Git repositories as the source of truth for the desired application state. It is implemented as a Kubernetes controller that continuously monitors running applications and compares their live state against the target state defined in Git. An application whose live state deviates from the target is marked OutOfSync. Argo CD visualises the differences and can sync the live state back to the target, either automatically or when a person triggers it.

Deployments can track a branch or tag, or be pinned to a specific commit, so the same mechanism supports both "always run the latest main" and "promote an exact revision". By default Argo CD polls Git every three minutes: the FAQ explains that timeout.reconciliation in the argocd-cm ConfigMap defaults to 120 seconds with 60 seconds of jitter. Webhooks from GitHub, Bitbucket and GitLab can trigger refreshes immediately instead of waiting for the next poll.

Core concepts

The documentation defines a small vocabulary that is worth learning before reading anything else:

• Application: a group of Kubernetes resources defined by a manifest, represented as a Custom Resource Definition.
• Target state: the desired state of an application as represented by files in Git.
• Live state: what is actually deployed, such as pods and services.
• Sync status: whether live state matches target state.
• Sync: the process of moving an application to its target state, for example by applying changes to a cluster.
• Refresh: comparing the latest code in Git with the live state to work out what differs.
• Health: whether the application is running correctly and can serve requests.
• Tool: the configuration management tool that turns a directory of files into manifests, such as Kustomize or Helm.

Components

The architecture overview describes three main components. The API server is a gRPC/REST server that backs the web UI, the CLI and CI/CD integrations. It handles application management and status reporting, invokes operations such as sync, rollback and user-defined actions, manages repository and cluster credentials (stored as Kubernetes Secrets), delegates authentication to external identity providers, enforces RBAC, and listens for Git webhook events.

The repository server is an internal service that keeps a local cache of the Git repositories holding application manifests. Given a repository URL, a revision, an application path and template settings such as Helm values, it generates and returns the Kubernetes manifests. The security documentation stresses that the repo-server carries no Kubernetes privileges and does not store credentials to other services.

The application controller is the Kubernetes controller that watches running applications, compares live and target state, detects OutOfSync applications, optionally takes corrective action and invokes lifecycle hooks (PreSync, Sync, PostSync). Since Argo CD 2.3 the ApplicationSet controller is bundled as well, adding templated generation of many Applications from one resource. The default installation also includes Redis, protected with a password stored in the argocd-redis Secret.

Key features

The feature list in the documentation is long; these are the capabilities most teams evaluate first:

• Multiple manifest formats: Kustomize applications, Helm charts, OCI images, Jsonnet, plain directories of YAML or JSON, and any custom tool registered as a config management plugin.
• Multi-cluster management: one Argo CD instance can deploy to the cluster it runs in and to external clusters registered with argocd cluster add.
• Automated or manual sync: syncs can be triggered by people through the UI or CLI, or run automatically whenever Git changes.
• Drift detection and visualisation: the UI shows which resources differ from Git, along with a resource tree, health status, logs and events.
• Rollback to any committed configuration: because every desired state lives in Git, any earlier revision can be redeployed.
• Health assessment: Argo CD analyses the health of application resources, not just whether they were applied.
• Sync hooks: PreSync, Sync and PostSync hooks support more involved rollouts; the docs cite blue/green and canary upgrades as examples.
• SSO and multi-tenancy: SSO integration covers OIDC, OAuth2, LDAP, SAML 2.0, GitHub, GitLab, Microsoft and LinkedIn, and RBAC policies plus projects separate teams.
• Automation access: project-scoped access tokens, a CLI designed for CI integration and webhook support.
• Observability: audit trails for application events and API calls, and Prometheus metrics.
• ApplicationSets: generators (List, Cluster, Git, OCI, Matrix and others) produce parameters that are substituted into a template, so one manifest can target many clusters or deploy many apps from a monorepo.

Getting started

The getting started guide assumes kubectl, a kubeconfig file and CoreDNS in the cluster. Installation creates a namespace and applies the official manifests from the stable branch:

kubectl create namespace argocd
kubectl apply -n argocd --server-side --force-conflicts -f https://raw.githubusercontent.com/argoproj/argo-cd/stable/manifests/install.yaml

The --server-side flag is required because some Argo CD CRDs, such as ApplicationSet, exceed the 262KB annotation limit of client-side apply. The --force-conflicts flag lets the apply take ownership of fields previously managed by other tools, which the guide notes will overwrite custom changes to fields defined in the official manifests. For production, the guide recommends pinning a version (it gives v3.2.0 as an example) rather than tracking stable.

The CLI is available from the GitHub releases page or through Homebrew on macOS, Linux and WSL:

brew install argocd

Argo CD is not exposed outside the cluster by default. Options include switching the argocd-server service to a LoadBalancer, configuring an ingress, or port forwarding for a quick look:

kubectl port-forward svc/argocd-server -n argocd 8080:443

The UI and API are then available at https://localhost:8080. The initial admin password is generated automatically and stored in clear text in the argocd-initial-admin-secret Secret. Retrieve it, log in and change it:

argocd admin initial-password -n argocd
argocd login <ARGOCD_SERVER>
argocd account update-password

The guide recommends deleting argocd-initial-admin-secret after changing the password; Argo CD recreates it only if a new admin password must be generated. Next, create an application from the project's example repository and deploy it:

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

The application starts as OutOfSync with health Missing, because nothing has been created yet. The sync retrieves the manifests from Git and applies them, after which the UI shows the resource tree, logs, events and health. The same steps can be done entirely in the web UI with the + New App button. To turn on automated sync for an existing application:

argocd app set <APPNAME> --sync-policy automated

Pruning and self-healing are separate opt-ins, enabled with --auto-prune and --self-heal or the matching fields in spec.syncPolicy.automated.

Installation options

The installation documentation distinguishes two families. The multi-tenant installation is the common one, typically maintained by a platform team and used by several application teams through the UI and CLI. It comes in a non-HA flavour (install.yaml, intended for evaluation, demos and testing, not production) and an HA flavour (ha/install.yaml) with multiple replicas of supported components, which the docs recommend for production. Each also has a namespace-install.yaml variant that needs only namespace-level privileges and relies on registered external clusters; with that variant the CRDs must be installed separately.

The core installation runs Argo CD headless: no API server and no UI, lightweight non-HA components, and fewer moving parts. It suits cluster administrators who use Argo CD on their own without multi-tenancy, and the CLI can talk to it with argocd login --core. Argo CD can also be installed with Kustomize, referencing the official manifest as a remote resource and patching it, or with a Helm chart that the docs note is community maintained in the argo-helm repository.

Use cases

• Pull-request driven deployments: developers change manifests or Helm values through reviewed pull requests, and merges roll out automatically with a full Git history of who changed what.
• Central platform for many teams: a platform team runs one HA Argo CD instance with SSO, projects and RBAC, and application teams self-serve deployments within the boundaries set for them.
• Fleet management: with ApplicationSets and the Cluster generator, the same add-ons or applications can be rolled out to every registered cluster, with per-cluster parameters substituted into a template.
• Monorepos: the Git generator can create one Application per directory or per JSON file in a repository, a scenario the ApplicationSet docs call out explicitly.
• Drift control: with self-healing enabled, manual changes made directly in the cluster are reverted to what Git declares, which keeps environments reproducible.
• Disaster recovery and rollback: because the desired state is in Git, rebuilding a cluster or returning to a known-good revision is a sync rather than a manual reconstruction.

How it compares

Argo CD sits in the GitOps continuous delivery category. The most commonly compared tool is Flux, another Kubernetes-native GitOps controller; the two share the core idea of reconciling clusters from Git but differ in architecture and user experience, and teams typically evaluate both against their own requirements. The README itself links to a third-party comparison of Argo CD with Spinnaker, Jenkins X and Tekton, which take broader pipeline-oriented approaches to delivery rather than focusing on reconciling Kubernetes state.

Compared with push-based CI scripts that run kubectl apply or helm upgrade from a pipeline, the main differences are that credentials stay inside the cluster, drift is detected continuously rather than only at deploy time, and the UI gives a live view of what is running. The trade-off is another stateful system to operate, and a stronger dependency on the security of the Git repositories Argo CD trusts. Argo CD also integrates with sibling projects: the README's resource list points to Argo Rollouts for progressive delivery and Argo CD Image Updater for automating image updates.

Things to know before adopting

• Git write access is deployment access. The security documentation warns that anyone who can write to a trusted repository can change what is deployed, including deploying malicious images or deleting resources so they are pruned. Malicious Helm charts or Kustomizations could also try to read files outside the application path on the repo-server, which matters if config management plugins hold secrets such as decryption keys.
• Allow-lists do not cover remote references. Argo CD's repository allow-list only restricts the initially cloned repository; Kustomize remote bases and Helm chart dependencies can pull in other repositories.
• Pruning is off by default. Automated sync will not delete resources removed from Git unless pruning is enabled. Separately, populating syncPolicy.manualDefaults makes manual syncs prune by default unless prune: false is set explicitly.
• Default TLS is self-signed. A fresh install uses a self-signed certificate; configure a proper certificate, trust the self-signed one, or use --insecure for testing only.
• Some traffic is unencrypted by default. Service-to-service traffic between the three main components uses TLS, but communication with Redis is plain by default and needs extra configuration to encrypt.
• Swagger UI is public. The /swagger-ui endpoint is unauthenticated by design; it can be disabled with server.disable.swagger.ui if you want a smaller unauthenticated surface.
• Cluster credentials are powerful. argocd cluster add creates an argocd-manager ServiceAccount bound to an admin-level ClusterRole in the target cluster. It can be narrowed, but cluster-wide get, list and watch are still required.
• Namespace assumptions. The manifests include ClusterRoleBindings that reference the argocd namespace; installing elsewhere requires patching them.
• HTTP/2 through proxies. The CLI uses gRPC over HTTP/2; behind an ingress that lacks HTTP/2 support, commands can time out unless gRPC is enabled on the ingress or --grpc-web is used.
• Scale tuning. The high-availability guide covers controller sharding across replicas for many clusters, repo-server parallelism and reconciliation timeouts; large fleets need deliberate tuning.

Project activity

As of November 2026 the argoproj/argo-cd repository has about 24,500 stars on GitHub. It was created in February 2018, is written in Go and is licensed under Apache-2.0. The most recent release at the time of writing is v3.5.7, published in early November 2026, and the repository received commits on the day of writing. The project runs weekly contributor office hours and a monthly user community meeting, and support is offered through GitHub Discussions and the #argo-cd Slack channel.

The source is at github.com/argoproj/argo-cd, and the full documentation, including the operator manual and user guide, is at argo-cd.readthedocs.io. A live demo instance is linked from the README at cd.apps.argoproj.io.

[![Featured on TechLogHub](https://techloghub.com/badge-neutral.svg)](https://techloghub.com/open-source/argo-cd?utm_source=techloghub_badge&utm_medium=referral&utm_campaign=readme)