ArgoCD Tutorial: Learn GitOps from Scratch (2026)
When I first adopted GitOps, the biggest mental shift was treating my Kubernetes cluster as a system that continuously converges toward the state described in Git. ArgoCD is the tool that made that vision real. It polls or watches your Git repository and automatically syncs your cluster to match the manifests there. No more kubectl apply from a laptop, no more drift between environments. Every change is reviewed through a pull request, every deployment is auditable, and rollback is a git revert away. This tutorial covers ArgoCD from installation to advanced sync strategies, drawing from production GitOps workflows I have implemented for teams shipping multiple times per day.
By the end of this tutorial, you will understand how ArgoCD implements the GitOps operator pattern, how to manage applications declaratively with Application CRDs, and how to design sync policies, automated pruning, and multi-cluster deployments that keep your Kubernetes workloads in lockstep with your repository.
Installing ArgoCD on Kubernetes
ArgoCD installs as a set of controllers in a dedicated namespace. The quickstart uses kubectl to apply the install manifests, but for production I recommend the Helm chart that gives you control over ingress, TLS, and resource allocations. The core components are the API server (gRPC and REST), the repository server that caches Git data, the application controller that reconciles state, and the Redis cache for performance. After installation, you access the web UI via port-forward or an Ingress resource. The default admin password is the pod name of the API server — change it immediately and configure SSO with Dex, Keycloak, or your identity provider. RBAC policies in the argocd-rbac-cm ConfigMap control what each user and group can see and do.
kubectl create namespace argocd
kubectl apply -n argocd -f https://raw.githubusercontent.com/argoproj/argo-cd/stable/manifests/install.yaml
kubectl port-forward svc/argocd-server -n argocd 8080:443
argocd admin initial-password -n argocdDefining Applications with Application CRDs
Every ArgoCD application is a Custom Resource that specifies the source repository, target cluster, destination namespace, and sync policy. The source can be a Helm chart, a Kustomize overlay, a directory of YAML files, or a Jsonnet project. I define applications declaratively in the same Git repository as the manifests they deploy — this is the GitOps chicken-and-egg problem that the App of Apps pattern solves. The project resource provides logical grouping and constraints: which clusters and namespaces an application can deploy to, which source repositories are allowed, and which resource types are permitted. Projects are how you enforce multi-tenant governance in shared clusters.
apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
name: guestbook
namespace: argocd
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
selfHeal: trueSync Strategies: Automated, Manual, and Phased
Sync policy determines how ArgoCD applies changes from Git to the cluster. Automated sync with pruning and self-healing is the full GitOps experience: any drift is immediately corrected, any resource not in Git is deleted. For databases and critical workloads, I use manual sync with a approve-and-promote workflow. The sync waves feature lets you control the order of resource application within a single sync — infrastructure CRDs first, then namespaces, then applications. Sync phases and waves are annotated on resources: argocd.argoproj.io/sync-wave: "-5" for CRDs, "0" for core workloads, "5" for smoke tests. This prevents race conditions where an application tries to create a resource before its CRD is registered.
metadata:
annotations:
argocd.argoproj.io/sync-wave: "-5"
spec:
syncPolicy:
automated:
prune: false
selfHeal: true
allowEmpty: false
syncOptions:
- CreateNamespace=true
- ApplyOutOfSyncOnly=trueThe App of Apps Pattern
Managing hundreds of microservices as individual ArgoCD applications becomes unwieldy. The App of Apps pattern uses a root application whose source is a directory of Application CRDs. When you add a new Application YAML to that directory and push to Git, ArgoCD syncs the root app, which discovers and creates the child apps. This gives you a single source of truth for all cluster applications. I organize the root app repository with subdirectories by team and environment: teams/team-a/production, teams/team-a/staging. Each team owns their Application files, and the platform team manages the root app. Health status aggregates up from child apps to the root, so the dashboard shows overall cluster health.
apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
name: root-app
namespace: argocd
spec:
project: default
source:
repoURL: https://github.com/myorg/cluster-apps.git
targetRevision: HEAD
path: apps
destination:
server: https://kubernetes.default.svc
namespace: argocd
syncPolicy:
automated:
prune: true
selfHeal: trueMulti-Cluster Management and Rollbacks
ArgoCD manages multiple clusters through cluster credentials stored as Secrets in the argocd namespace. The argocd cluster add command registers a cluster by installing a ServiceAccount and generating a kubeconfig. I manage staging, production, and disaster-recovery clusters from a single ArgoCD instance. Cluster labels enable targeting specific clusters for application deployments. Rollbacks in ArgoCD are trivial because every deployment state is a commit in Git. ArgoCD tracks application state history, and with a single click — or argocd app rollback — you return to any previous sync. The rollback creates a new sync to the previous Git revision, not a Kubernetes-level undo, so the rollback is itself auditable and follows the same sync process.
argocd cluster add context-prod --label env=prod --label region=us-east-1
argocd cluster list
argocd app rollback guestbook --prune
argocd app get guestbook
kubectl get applications -n argocd -o wideSecurity, Webhooks, and Notifications
ArgoCD security starts with RBAC: map your SSO groups to ArgoCD roles through the argocd-rbac-cm ConfigMap. The policy format uses Casbin rules. I restrict who can sync to production and who can delete applications. Webhooks from GitHub or GitLab trigger automated syncs when you push to specific branches — configure the webhook URL pointing to your ArgoCD instance and the shared secret. For notifications, ArgoCD Notifications is a separate controller that sends email, Slack, or webhook alerts on sync status, health changes, and warnings. I configure notifications for failed syncs in production and successful syncs in staging. The ConfigMap-based notification templates let you customize messages with application name, sync status, and commit details.
apiVersion: v1
kind: ConfigMap
metadata:
name: argocd-notifications-cm
namespace: argocd
data:
template.deployment-failed: |
message: Deployment {{.app.name}} failed.
trigger.on-sync-failed: |
- when: app.status.sync.status == 'OutOfSync'
send: [deployment-failed]Frequently Asked Questions
What is the difference between ArgoCD and Flux?
Both are GitOps operators for Kubernetes. ArgoCD is push-based — it actively syncs the cluster to match Git. Flux is pull-based — the cluster pulls from Git through a reconciliation loop. ArgoCD has a richer web UI, supports multiple config tools (Helm, Kustomize, Jsonnet), and has a mature RBAC model. Flux is lighter and integrates natively with the Kubernetes controller-runtime pattern. Both are excellent; choose ArgoCD for multi-cluster management and Flux for a simpler, more Kubernetes-native approach.
Is ArgoCD only for Kubernetes?
ArgoCD is specifically designed for Kubernetes. However, the Argo project includes Argo Workflows for Kubernetes-native workflow orchestration, Argo Rollouts for progressive delivery, and Argo Events for event-driven automation. The GitOps pattern itself can apply to any infrastructure, but ArgoCD specifically manages Kubernetes resources.
How do I handle secrets in ArgoCD?
ArgoCD integrates with external secret management tools. Use Sealed Secrets to encrypt secrets in Git, or the argocd-vault-plugin to substitute placeholders with values from HashiCorp Vault at sync time. External Secrets Operator is another common pattern where a separate controller creates Secrets from external stores before ArgoCD syncs.
Can ArgoCD manage Helm charts with values from multiple environments?
Yes. The Application CRD supports Helm value files via the source.helm.valueFiles parameter pointing to files in the repository. You can also pass inline values with source.helm.parameters. For environment-specific values, maintain separate value files for dev, staging, and prod, or use Kustomize overlays with Helm charts as bases.
Originally published on Ayodhyyya. Last updated June 1, 2026.