Complete Guide to GitOps with ArgoCD
Deploy Kubernetes apps with GitOps and ArgoCD: installation, ApplicationSets, sync strategies, Helm/Kustomize, RBAC, and multi-cluster.
Introduction
GitOps uses Git as the single source of truth for infrastructure and application deployment. ArgoCD is a Kubernetes-native continuous delivery tool built on GitOps — it watches a Git repository and syncs the desired state to Kubernetes clusters. The following guide covers installation, application configuration, sync strategies, Helm/Kustomize integration, RBAC, and multi-cluster management.
The model inverts the classic push pipeline: instead of CI deploying to the cluster with kubectl apply, a controller inside the cluster pulls desired state from Git and reconciles it continuously. CI’s job shrinks to “build image, update manifest, open PR” — the deploy step is gone, along with the credentials that made it possible.
GitOps Principles
- Declarative: System state is described declaratively in Git — manifests, Helm values, Kustomize overlays, not imperative scripts
- Versioned: Git gives you versioning, history, and rollback —
git revertis the rollback path - Pulled: ArgoCD pulls changes from Git (no push from CI — the cluster credentials never leave the cluster)
- Continuously reconciled: ArgoCD detects drift and corrects it — manual
kubectledits get reverted when selfHeal is on
That last point is the one people underestimate: GitOps isn’t just “deploy on merge”. The controller watches live state too — someone kubectl edits a replica count at 2am, ArgoCD sees the drift and puts it back. Git stays the truth.
ArgoCD vs Flux
Both are CNCF GitOps operators, and the choice is real:
| ArgoCD | Flux |
|---|---|
| UI + RBAC + SSO built in | CLI-first, UI via third parties (Weave GitOps, Headlamp) |
| Application CRD + ApplicationSet | FluxCD Kustomization/HelmRelease CRDs |
| Multi-cluster out of the box | Cluster API or custom wiring for multi-cluster |
| Notifications controller included | Alerting via notification-controller (webhooks) |
| Heavier footprint (several components) | Lighter — runs as a small set of controllers |
Teams with many namespaces and non-expert users usually pick ArgoCD for the UI; teams already fluent in Kubernetes internals who want minimal moving parts lean Flux. This guide is the ArgoCD deep-dive — for the side-by-side decision in a production workflow, see the GitOps production guide.
Installing ArgoCD
kubectl create namespace argocd
kubectl apply -n argocd \
-f https://raw.githubusercontent.com/argoproj/argo-cd/stable/manifests/install.yaml
# Get admin password
kubectl -n argocd get secret argocd-initial-admin-secret \
-o jsonpath="{.data.password}" | base64 -d
# Port-forward to access UI
kubectl port-forward svc/argocd-server -n argocd 8080:443
For real deployments skip port-forward — put argocd-server behind an ingress with TLS, enable SSO (Dex/OIDC with GitHub or Google) instead of the admin account, and use the HA install manifest (install.yaml has a -ha variant) when ArgoCD itself is critical. The initial admin secret is a bootstrap path, not a credential management strategy.
Basic Application
apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
name: my-app
namespace: argocd
spec:
project: default
source:
repoURL: https://github.com/example/my-app-deploy
targetRevision: main
path: manifests
destination:
server: https://kubernetes.default.svc
namespace: my-app
syncPolicy:
automated:
prune: true
selfHeal: true
syncOptions:
- CreateNamespace=true
The pieces that matter: source points at the repo+path+revision that holds desired state, destination names the cluster+namespace to deploy into, and syncPolicy.automated is where the GitOps contract lives — prune: true deletes resources that disappear from Git, selfHeal: true reverts out-of-band cluster edits, and syncOptions tweaks edge cases like auto-creating the destination namespace. For the production view of this workflow (SOPS, progressive delivery, rollback), see the GitOps production guide.
ApplicationSet (Multi-Environment)
apiVersion: argoproj.io/v1alpha1
kind: ApplicationSet
metadata:
name: my-app-multi-env
namespace: argocd
spec:
generators:
- list:
elements:
- env: dev
cluster: https://dev-cluster:6443
- env: staging
cluster: https://staging-cluster:6443
- env: prod
cluster: https://prod-cluster:6443
template:
metadata:
name: "my-app-{{env}}"
spec:
project: default
source:
repoURL: https://github.com/example/my-app-deploy
targetRevision: main
path: "manifests/{{env}}"
destination:
server: "{{cluster}}"
namespace: my-app
syncPolicy:
automated:
prune: true
selfHeal: true
syncOptions:
- CreateNamespace=true
The list generator is the explicit option — you enumerate dev/staging/prod and the template stamps out one Application per element. Generators are the real power here:
list— fixed set of envs/clusters (what you saw above)git— discover Applications from directories or files in a repocluster— one Application per registered ArgoCD clusterpullRequest— preview environments: an Application per open PRmatrix— cartesian product of two generators (env × region)
For production the pullRequest generator is the big win — every PR gets a preview namespace with the PR’s manifests deployed, destroyed on merge.
Git Generator (Auto-discover repos)
The git generator turns directory structure into Applications — a folder per service or env in the deploy repo, and every new directory becomes a new Application on the next reconcile. Adding a service means adding a folder, nothing else. directories walks folders; files reads a manifest per file (useful for per-team config repos).
apiVersion: argoproj.io/v1alpha1
kind: ApplicationSet
metadata:
name: auto-discover
namespace: argocd
spec:
generators:
- git:
repoURL: https://github.com/example/org-deployments
directories:
- path: "*/"
template:
metadata:
name: "{{path.basename}}"
spec:
project: default
source:
repoURL: https://github.com/example/org-deployments
targetRevision: main
path: "{{path}}"
destination:
server: https://kubernetes.default.svc
namespace: "{{path.basename}}"
syncPolicy:
automated:
prune: true
selfHeal: true
syncOptions:
- CreateNamespace=true
Helm Integration
ArgoCD renders Helm charts natively — no Tiller, no Helm CLI in the cluster. valueFiles layer base→environment overrides in order; parameters are individual key overrides that win over both. Keep environment-specific values in the deploy repo (not the chart’s defaults) so the Application stays the only knob you turn per env.
apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
name: my-app-helm
namespace: argocd
spec:
project: default
source:
repoURL: https://github.com/example/my-app-deploy
targetRevision: main
path: charts/my-app
helm:
valueFiles:
- values.yaml
- values-prod.yaml
parameters:
- name: image.tag
value: "v1.2.3"
- name: replicaCount
value: "3"
destination:
server: https://kubernetes.default.svc
namespace: my-app
syncPolicy:
automated:
prune: true
selfHeal: true
Kustomize Integration
The path points at an overlay — base/ holds the shared manifests, overlays/dev and overlays/prod patch replicas, resources, and image tags. kustomize.images in the Application is a last-minute override, mostly for CI updating the tag. Base stays untouched; overlays own the env-specific deltas.
apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
name: my-app-kustomize
namespace: argocd
spec:
project: default
source:
repoURL: https://github.com/example/my-app-deploy
targetRevision: main
path: overlays/production
kustomize:
images:
- my-app:v1.2.3
commonLabels:
env: production
destination:
server: https://kubernetes.default.svc
namespace: my-app
syncPolicy:
automated:
prune: true
selfHeal: true
Sync Strategies
The sync policy decides when desired state becomes live state. The rule of thumb: automated with selfHeal for dev/staging, manual or sync-windowed for production — one bad manifest shouldn’t reach prod unattended.
Automated sync
syncPolicy:
automated:
prune: true # Delete resources removed from Git
selfHeal: true # Revert manual changes
Manual sync with hooks
syncPolicy:
syncOptions:
- CreateNamespace=true
- PrunePropagationPolicy=foreground
# Manual sync via CLI: argocd app sync my-app
Sync waves (ordered deployment)
# In your manifests, add annotations:
metadata:
annotations:
argocd.argoproj.io/sync-wave: "0" # Runs first
---
metadata:
annotations:
argocd.argoproj.io/sync-wave: "1" # Runs second
---
metadata:
annotations:
argocd.argoproj.io/sync-wave: "2" # Runs third
Waves run in ascending order and the sync waits for each wave to report Healthy before starting the next — that’s what lets you land CRDs before the custom resources that need them, or the ConfigMap before the deployment that mounts it. Negative waves run before 0 (use them for namespaces and CRDs).
Sync windows
Block deploys outside business hours without touching the Application:
# In AppProject spec
syncWindows:
- kind: deny
schedule: '0 0 * * SAT,SUN' # no weekend deploys
duration: 24h
applications: ['*']
- kind: allow
schedule: '0 9-17 * * MON-FRI'
duration: 8h
applications: ['*']
Pre/Post sync hooks
apiVersion: batch/v1
kind: Job
metadata:
name: db-migration
annotations:
argocd.argoproj.io/hook: PreSync
argocd.argoproj.io/hook-delete-policy: HookSucceeded
spec:
template:
spec:
containers:
- name: migration
image: my-app/migrate:v1.2.3
command: ["./migrate", "up"]
restartPolicy: Never
backoffLimit: 3
Hooks run at lifecycle points: PreSync before the main sync (migrations, schema changes), PostSync after resources are healthy (smoke tests), SyncFail on failure (alerts, cleanup), Skip to exclude a resource from sync entirely. hook-delete-policy controls when the hook resource gets cleaned up — HookSucceeded for fire-and-forget jobs.
RBAC
ArgoCD RBAC is Casbin policy in a ConfigMap — p rules grant subject, resource, action, object, effect, g maps users/groups to roles. Pair it with AppProject for real multi-tenancy: the project constrains which repos, clusters, and namespaces Applications in it may touch, and the RBAC decides who can do what inside that fence.
# argocd-rbac-cm
apiVersion: v1
kind: ConfigMap
metadata:
name: argocd-rbac-cm
namespace: argocd
data:
policy.default: role:readonly
policy.csv: |
p, role:dev-team, applications, sync, dev/*, allow
p, role:dev-team, applications, get, dev/*, allow
p, role:dev-team, applications, action/override, dev/*, deny
p, role:ops-team, applications, *, */*, allow
g, dev-team, role:dev-team
g, ops-team, role:ops-team
# AppProject — the fence around a team's apps
apiVersion: argoproj.io/v1alpha1
kind: AppProject
metadata:
name: dev
namespace: argocd
spec:
sourceRepos: ['https://github.com/example/*'] # only these repos
destinations:
- server: '*' # any cluster
namespace: 'dev-*' # only dev-* namespaces
clusterResourceWhitelist:
- group: ''
kind: Namespace # may create namespaces only
Multi-Cluster Management
# Register a cluster with ArgoCD
argocd cluster add prod-cluster --label environment=production
# List registered clusters
argocd cluster list
# Deploy to a specific cluster
apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
name: my-app-prod
namespace: argocd
spec:
source:
repoURL: https://github.com/example/my-app-deploy
targetRevision: main
path: overlays/production
destination:
server: https://prod-cluster:6443 # or name: prod-cluster
namespace: my-app
Registered clusters live as secrets labeled argocd.argoproj.io/secret-type: cluster in the argocd namespace — argocd cluster add just writes that secret. Combined with the ApplicationSet cluster generator, adding a new cluster = adding one secret, and every Application in the set deploys there automatically.
ArgoCD CLI
The CLI mirrors the UI — anything you can click, argocd app <verb> can do in scripts and pipelines.
# Login
argocd login localhost:8080 --username admin --password <password>
# Application management
argocd app create my-app \
--repo https://github.com/example/my-app-deploy \
--path manifests \
--dest-server https://kubernetes.default.svc \
--dest-namespace my-app
argocd app sync my-app
argocd app get my-app
argocd app history my-app
argocd app rollback my-app <version>
argocd app delete my-app
# Diff between Git and cluster
argocd app diff my-app
# Utilities that save you in incidents
argocd app wait my-app --health --timeout 120 # block until Healthy in CI
argocd app sync my-app --dry-run # preview the apply
argocd admin settings rbac can "get, applications" --policy-file argocd-rbac-cm # test RBAC locally
argocd app diff before merge and argocd app sync --dry-run in CI are the two commands that prevent most GitOps incidents — the diff shows exactly what would change in the cluster for a given manifest.
Notifications
apiVersion: v1
kind: ConfigMap
metadata:
name: argocd-notifications-cm
namespace: argocd
data:
service.slack: |
token: $slack-token
trigger.on-deployed: |
- when: app.status.operationState.phase in ['Succeeded']
send: [app-deployed]
template.app-deployed: |
message: |
{{.app.metadata.name}} deployed to {{.app.status.sync.status}}
Notifications run on the notifications-controller: service.* defines channels (slack, email, webhook, pagerduty), trigger.* the conditions (sync-succeeded, sync-failed, health-degraded, created, deleted), template.* the payload with Go templating over the Application object. Subscribe per-Application or per-ApplicationSet via the notifications.argoproj.io/subscribe.on-deployed.slack: my-channel annotation — no per-app config needed.
Repository Layout
Two layouts cover most teams. App-of-apps: one repo with an Application per environment/service, and a root Application that points at the folder containing them — one bootstrap deploys the whole tree:
deploy-repo/
├── apps/ # Application manifests (the "app of apps")
│ ├── dev.yaml # Application → overlays/dev
│ ├── staging.yaml
│ └── prod.yaml
├── base/ # Kustomize base or plain manifests
└── overlays/
├── dev/ # dev patches (1 replica, small limits)
├── staging/
└── prod/ # prod patches (3 replicas, full limits)
Separate deploy repo vs same repo: keeping manifests in the app repo couples deploy frequency to code merges (every commit triggers a reconcile). A dedicated deploy repo decouples them — CI builds the image, updates the tag in the deploy repo, and ArgoCD picks it up. That separation is what makes multi-env promotion a git operation instead of a redeploy.
Troubleshooting
- App stuck in
SyncWait: usually a hook that never completes (a Job that doesn’t reach Succeeded) or a resource whose health ArgoCD can’t assess — checkargocd app get my-appfor the hanging resource and its events. OutOfSyncthat won’t heal: something outside ArgoCD’s tracking (manualkubectl, a webhook-mutated field, an admission controller injecting sidecars) — diff withargocd app diff my-app; if the delta is a controller-managed field, add it toignoreDifferencesin the Application.- CRD-dependent resources fail: the CRD and its CRs land in the same sync but the API isn’t registered yet — use sync waves (CRD in wave
-1or0, CRs later) so the API exists before it’s used. - Refresh vs hard refresh:
argocd app get my-app --refreshre-polls the repo;--hard-refreshclears the manifests cache too — use it when “nothing changed” but you know it did. - Sync works but resources get recreated:
prune: truedeletes orphaned resources every sync — checkargocd app resources my-appfor what’s being pruned and add tracking (app.kubernetes.io/instancelabel) where it belongs.
Production Checklist
Before calling an ArgoCD setup “production ready”:
- HA install — use the
install.yamlHA variant (3 replicas of each component, anti-affinity across nodes) so a node failure doesn’t take your delivery pipeline down - SSO only — disable the admin account (
argocd-cmadmin.enabled: "false"), route everything through Dex/OIDC; local accounts are for break-glass only - Projects per team — one AppProject per team or env, with
sourceRepos,destinations, andclusterResourceWhitelistconstrained; never letdevapps reachprodnamespaces - Separate deploy repo — manifests live in their own repo; CI updates tags there, never in app code
- Sync windows for prod — deny windows outside business hours; allow windows when humans are around to watch
- Alerts on drift and failure — notifications on
sync-failed,health-degraded, and OutOfSync that persists past a few minutes - Backups of ArgoCD state —
argocd-util exportregularly; the Applications and projects are state too - Monitored controller — ArgoCD is critical infrastructure: alert on its own health, memory, and git fetch errors, not just on the apps it deploys
- Secrets operator — Sealed Secrets, SOPS, or External Secrets; plain secrets in Git are a leak waiting to happen
Best Practices
-
For a deeper guide, see Complete Guide to GitOps in Production.
-
Store manifests separately from app code — separate deploy repo or directory
-
Use Kustomize overlays — base + per-environment overlays
-
Enable selfHeal — revert manual kubectl changes automatically
-
Use sync waves — ensure CRDs are applied before resources that use them
-
Use AppProject for isolation — restrict which repos, clusters, and namespaces each team can access
-
Pin ArgoCD version — don’t use
latestin production -
Use SSO for ArgoCD — integrate with GitHub, Google, or OIDC
-
Monitor ArgoCD itself — it’s critical infrastructure
-
Use ApplicationSets for scale — avoid creating individual Applications for each microservice
-
Enable notifications — alert on sync failures and drift detection
Common Mistakes
- Storing manifests in the app repo — coupling deploy frequency to app release frequency
- Not using selfHeal — manual changes persist and cause drift
- Giving all teams admin access — use RBAC with least privilege
- Not using sync waves — CRDs and operators fail if applied out of order
- Not testing sync before merging — use ArgoCD diff or
argocd app sync --dry-run - Using automated sync in production without canary — consider manual sync for prod
- Not monitoring drift — enable notifications for out-of-sync status
- Forgetting to prune — old resources persist if
prune: false
See Also
- ArgoCD official docs
- ApplicationSet documentation
- Complete Guide to GitOps in Production — SOPS, progressive delivery, rollbacks
- Complete Guide to Kubernetes Ingress
- ArgoCD companion on GitHub — Application, ApplicationSet, AppProject, notifications YAMLs
Frequently Asked Questions
How is GitOps different from CI/CD?
CI builds and tests code. GitOps handles CD — deployment to environments. In GitOps, the deployment is triggered by Git changes, not by CI pushing to a cluster. CI builds images and updates manifests in Git; ArgoCD picks up the manifest change and deploys.
Should I use automated sync in production?
It depends. Automated sync with selfHeal is great for dev and staging. For production, consider manual sync with approval gates, or automated sync with progressive delivery (Argo Rollouts) for canary/blue-green deployments.
How do I handle secrets in GitOps?
Don't store plain secrets in Git. Use Sealed Secrets, SOPS, or External Secrets Operator. These encrypt secrets at rest in Git and decrypt them in the cluster. ArgoCD syncs the encrypted version; the operator handles decryption.
Should I use ApplicationSet or individual Applications?
ApplicationSet once you've got more than a couple of environments or clusters — one template stamps out N Applications from a generator, so adding prod-eu or a new team is a line in the generator, not a new YAML file. Individual Applications only make sense for one-off cases.
How do I roll back a bad deploy?
argocd app rollback my-app <version> — the app history records every sync, so rollback is a new sync to an old state (still GitOps: it's recorded and reversible). git revert works too and is the better long-term answer since it keeps Git honest.
Can I deploy without a Git commit for quick fixes?
You can — argocd app sync my-app --local manifests/ or an ad-hoc kubectl apply — but selfHeal will revert it on the next reconcile, which is exactly the point. For real emergencies: sync to a hotfix branch, or pause auto-sync, patch, and commit the fix properly. The cluster isn't the source of truth; treat out-of-band changes as temporary.
Related Resources
Kubernetes Basics for Application Developers
Learn the core Kubernetes concepts every developer needs: Pods, Services, Deployments, ConfigMaps, and basic kubectl commands.
GuideCI/CD Pipeline Guide: From Commit to Production
A practical guide to building CI/CD pipelines with GitHub Actions, testing gates, deployment strategies, and rollback procedures.
GuideDeployment Strategies Compared: Blue-Green, Canary, Rolling
A practical guide to deployment strategies: rolling, blue-green, canary, shadow and feature flags. Minimize risk and rollback time when releasing to production.
GuideComplete Guide to Kubernetes Ingress
Configure and troubleshoot Kubernetes Ingress. Covers controllers, TLS with cert-manager, path routing, annotations, and the move to Gateway API.
GuideComplete Guide to CI/CD with GitHub Actions
Build CI/CD pipelines from scratch with GitHub Actions. Covers workflows, runners, matrix builds, caching, secrets, environments, deployment strategies, and reusable workflows.
GuideKubernetes Config Management Guide
Kubernetes configuration management: ConfigMaps, Secrets, External Secrets Operator, sealed secrets, env injection, mounts, and rotation.