Skip to main content
This article explains the synchronization strategies Argo CD uses to apply changes from a Git repository to a Kubernetes cluster. Understanding these options helps you choose the right GitOps behavior for your environment—whether you prefer hands-off deployment, strict cluster hygiene, or automatic recovery from out-of-band changes. Argo CD sync policies determine how and when Git changes are propagated to the cluster:
  • Manual vs Automatic sync
    • Automatic sync: Argo CD applies new or changed manifests from Git to the cluster as soon as it detects them (for example via a webhook).
    • Manual sync: Argo CD detects the change but waits for a user or operator to trigger the sync operation.
  • Auto-pruning
    • With pruning enabled, resources removed from Git are deleted from the target cluster during the next sync.
    • With pruning disabled, deleting manifests from Git does not remove the corresponding resources from the cluster.
  • Self-heal (automatic reconciliation of out-of-band changes)
    • With self-heal enabled, Argo CD automatically reverts manual or out-of-band changes made directly to the cluster (for example via kubectl), restoring the state defined in Git.
    • With self-heal disabled, Argo CD does not automatically revert such manual changes.
Key points about the Argo CD syncPolicy automated block:
  • Presence of the automated block enables automatic sync; there is no enabled boolean—omitting automated leaves sync manual.
  • automated.prune: true enables automatic deletion of resources removed from Git.
  • automated.selfHeal: true enables automatic reconciliation of out-of-band cluster changes.
A minimal Application snippet that enables automatic sync, pruning, and self-heal looks like this: 
# Example: Application.spec.syncPolicy to enable auto-sync, pruning, and self-heal
spec:
  syncPolicy:
    automated:
      prune: true      # delete resources removed from Git
      selfHeal: true   # revert out-of-band changes in the cluster
# To keep sync manual, remove the entire `automated` block above.
Assume an Application tracks a Git repo that initially contains deployment.yaml and configmap.yaml. A webhook is set up so Argo CD learns about Git changes immediately. Below are four common combinations of flags and their effects.
  1. Automatic sync only (prune = false, selfHeal = false)
  • Adding service.yaml to Git: Argo CD applies it automatically to the cluster.
  • Deleting service.yaml from Git: Argo CD does not remove the service from the cluster (no auto-prune).
  • Manually deleting the configmap in the cluster via kubectl: Argo CD will not recreate it (self-heal disabled).
  1. Automatic sync + Auto-pruning (prune = true, selfHeal = false)
  • Adding service.yaml to Git: applied automatically.
  • Deleting service.yaml from Git: Argo CD removes that resource from the cluster on the next sync (auto-prune enabled).
  • Manually deleting the configmap in the cluster: Argo CD does not restore it (self-heal disabled).
  1. Automatic sync + Self-heal (prune = false, selfHeal = true)
  • Adding service.yaml to Git: applied automatically.
  • Deleting service.yaml from Git: resource remains in cluster (prune disabled).
  • Manually deleting the configmap in the cluster: Argo CD detects drift and recreates the resource from Git (self-heal enabled).
  1. Automatic sync + Auto-prune + Self-heal (prune = true, selfHeal = true)
  • Adding service.yaml to Git: applied automatically.
  • Deleting service.yaml from Git: resource is removed from the cluster (auto-prune enabled).
  • Manually deleting the configmap in the cluster: Argo CD recreates it from Git (self-heal enabled).
For quick comparison, here is a summary table of these scenarios:
ScenariopruneselfHealNew manifest added to GitManifest removed from GitManual deletion in cluster
1. Auto sync onlyfalsefalseApplied automaticallyNot removed from clusterNot restored
2. Auto sync + prunetruefalseApplied automaticallyRemoved from cluster on syncNot restored
3. Auto sync + self-healfalsetrueApplied automaticallyNot removed from clusterRestored automatically
4. Auto sync + prune + self-healtruetrueApplied automaticallyRemoved from cluster on syncRestored automatically
The following diagram visualizes these GitOps flows (initial Git repo: deployment.yml, configmap.yml) and shows what happens when service.yml or configmap resources are deleted under different sync options.
A labeled diagram showing GitOps workflows between a GitHub repo (deployment.yml, configmap.yml), Argo CD, and a Kubernetes cluster illustrating what happens when service.yml or configmap resources are deleted. It highlights three behaviors—manual/automatic sync, auto-pruning of resources, and self-heal of the cluster—using icons and step-by-step flows.
In summary:
  • Use automatic sync to apply Git changes immediately and reduce manual steps.
  • Enable prune to ensure the cluster mirrors deletions made in Git.
  • Enable self-heal to automatically reconcile manual or out-of-band changes so the cluster continuously matches the Git-defined state.
Links and references:

Watch Video