Argo CD automated sync, self-heal and prune settings

Argo CD automated sync: how far should Argo CD act on its own?

A platform team has to decide whether a commit to the Git repository should reach the cluster without a person clicking Sync, and whether a manual change made directly in the cluster should be reverted. Automated sync answers the first question, and the self-heal setting answers the second. Both are opt-in. Argo CD is released under the Apache License 2.0 (SPDX: Apache-2.0), and the project itself offers no paid edition, so the decision is about your own operating model rather than a license tier.

With automated sync enabled, Argo CD syncs an application whenever it finds the live state out of step with Git. It does not do this by default in every direction. prune is false unless you set it to true, so resources removed from Git stay in the cluster. allowEmpty is also false, which blocks a sync that would leave an application with no resources. selfHeal is off as well, so a manual change in the cluster stays until someone reverts it or a sync runs. When self-heal is on, the default self-heal timeout is 5 seconds. Automated sync also runs only for OutOfSync applications, does not retry a failed sync against the same commit and parameters, and disables rollback. The reconciliation check interval is set by timeout.reconciliation in argocd-cm, which defaults to 120 seconds plus up to 60 seconds of jitter. Confirm these values in your installed version before you rely on them.

Teams usually need automated sync when they run many clusters or frequent releases and want Git to be the only path to production. Turn on prune only after you have checked which resources would be deleted, and turn on selfHeal only where teams have agreed that manual fixes in the cluster are not allowed to persist. Ask your partner or internal owners to document which applications are automated, which are manual, and who may pause automation during an incident. Because rollback is unavailable while automation is on, your recovery path should be a Git revert or a planned manual sync. The automated sync policy guide lists these behaviors in full.

Which automated sync settings fit each deployment policy

This table compares each automated sync option against its default, what it changes in the cluster, and when it fits or becomes risky. Read it row by row to choose the policy for a given environment, starting with the most conservative setting for production. The main takeaway is that automation is safest when prune, self-heal and empty-sync blocking are each chosen on purpose rather than enabled together by default.

Setting	Default and effect	Fits or risky when
Automated sync	Off by default. When on, Argo CD syncs only applications that are OutOfSync, and it disables rollback.	Fits non-production or low-risk services with reviewed Git flow. Risky for production without an approved manual rollback path.
prune	False by default. When false, resources removed from Git stay in the cluster after sync.	Fits when teams delete resources in Git and expect cleanup. Risky when other tools or operators create objects Argo CD should not delete.
allowEmpty	False by default. Syncs that would leave an application with no resources are blocked.	Keep false for most apps. Enable only for applications that are intentionally scaled to zero resources and where accidental emptying is reviewed.
selfHeal	False by default. When false, manual changes in the cluster are not reverted by automation.	Fits strict GitOps where Git is the only source of change. Risky for workloads that controllers or operators modify at runtime, such as replica counts set by autoscalers.
Self-heal timeout	5-second default, per the automated sync guide. This is the delay before Argo CD corrects a manual change.	Keep the default unless a controller races with Argo CD. Increasing it gives other controllers time to reconcile first.
Retry behavior	Automated sync does not retry a failed sync against the same commit and parameters.	Plan for a new commit or a manual sync after failures. Confirm how retry is configured in your version before relying on it for production.
timeout.reconciliation	Set in argocd-cm. 120 seconds plus up to 60 seconds of jitter by default, per the automated sync guide.	Lower values detect drift sooner but add load on the repo server and API. Raise values in large installations with many applications.
Rollback	Unavailable while automated sync is enabled, per the automated sync guide.	Plan recovery by reverting the commit in Git. Confirm your recovery runbook before enabling automation on critical applications.

How to enable automated sync safely in sequence

This sequence moves one application at a time from manual sync to automated sync, prune and self-heal, with a verification check after each change so the team knows exactly which behavior it has turned on.

Confirm access controls before enabling automation
Before any automation is switched on, the platform team confirms that the built-in admin user is used only for setup, that local users or SSO are configured, and that admin.enabled is set to false. Confirm that RBAC for applications is scoped per project, and that update and delete permissions are granted only to the people and service accounts that should change Applications. Done means a named admin is the only account with broad rights, and a test user without sync rights cannot change the Application's settings. Repeat this check after any RBAC change, because automation makes an overly broad role more consequential.
Confirm the baseline with manual sync
Pick one non-production Application and leave automated sync off. The platform team pushes a known change to the Git repository and confirms that Argo CD marks the Application OutOfSync, shows the expected diff, and does not change the cluster until someone clicks sync. Next, make a small drift in the cluster, such as editing a label with kubectl, and confirm the Application shows OutOfSync with no automatic correction. Done means the team has seen both detection paths work and knows what manual behavior looks like for this Application.
Enable automated sync without prune or self-heal
On the same non-production Application, enable the automated sync policy with prune and selfHeal left at their defaults of off. Push a Git change that adds a resource and one that modifies an existing resource. The platform team checks that Argo CD applies the Git change without a manual click and that the Application returns to Synced. Also confirm that removing a manifest from Git leaves the old resource in the cluster, since prune is not yet enabled. Done means automated apply works and deletion is still manual.
Verify deletion behavior before turning on prune
Remove a non-critical resource from the Git repository and observe the Application. Argo CD reports the resource as OutOfSync but does not delete it while prune is off. The team then enables prune on the test Application and repeats the removal. Confirm the resource is deleted only after the Git commit, and check that the Application's status reflects the change. Also confirm that allowEmpty remains unset, so a commit that would leave the Application with no resources is blocked rather than wiping the namespace. Done means deletions happen only when intended and the empty-application guard is active.
Turn on self-heal and test manual cluster changes
With prune confirmed, enable selfHeal on the same Application. Make a manual change in the cluster, for example scaling a Deployment or editing an annotation, and confirm Argo CD reverts it to the Git state after the self-heal timeout. The default self-heal timeout is 5 seconds, so the team should confirm the setting in its own configuration. Also check that a manual change needed for an incident is understood to be overwritten, and that the on-call process says to change Git instead. Done means the cluster converges to Git after an out-of-band edit.
Check retry and reconciliation behavior
Confirm how a failed sync behaves. Automated sync does not retry a failed sync against the same commit and parameters, so the team should trigger a deliberately failing manifest in the test environment, fix it with a new commit, and verify that a new sync runs. Then review the reconciliation interval, which is set by timeout.reconciliation in argocd-cm with a default of 120 seconds plus up to 60 seconds of jitter. Record the value your environment uses so operations staff know how quickly changes are picked up.
Document rollback limits and extend to other applications
Automated sync disables the rollback action in the interface, so recovery depends on reverting the Git commit. Confirm that the team can run a revert, push it, and watch the Application return to the earlier state. Write the outcome of each check into the runbook, then repeat the sequence for the next Application group, starting with lower-risk workloads. Done means every enabled setting has a recorded check and a documented recovery path.

What triggers a sync when automation is on

Automated sync only acts on applications that Argo CD already reports as OutOfSync. Argo CD compares the desired state in Git with the live state in the cluster on a fixed check interval, controlled by timeout.reconciliation in argocd-cm. The default is 120 seconds plus up to 60 seconds of jitter, so a drift caused by a manual change may take between two and three minutes to be noticed, and the jitter spreads checks out across many applications. Teams with change-sensitive workloads should confirm the interval their own environment uses, because a shorter interval raises load on the controller and repo-server, and a longer one widens the window in which a manual edit stays live. Self-heal timing is separate and is governed by its own 5-second default timeout, so the two settings should be reviewed together.

A failed sync is not retried against the same commit and parameters. Once a sync fails, automation waits for something to change, such as a new commit, a changed parameter or a fresh manual sync, before it tries again. Teams that expect a transient API error to be retried automatically will be surprised, so the alerting and on-call runbook should assume that a failed application stays failed until someone acts on it. Confirm how your team wants failures surfaced, for example through notifications or dashboards, before enabling automation on production applications.

Rollback is disabled once automated sync is on, so plan the Git revert path in advance. The manual rollback action in the Argo CD interface is not available for automated applications, which means the recovery route is to revert the offending commit in Git and let automation sync the reverted state. This only works if reverts are fast, reviewed under your change process and tested, including the case where the bad commit also changed database schema or secrets. Document the revert procedure, who may perform it, and how it is recorded, and rehearse it on a non-production application before relying on it.

Risks of letting Argo CD change the cluster unattended

Automated sync moves changes from Git into the cluster without a person pressing sync. Each risk below comes from a setting that can be left on by default or set too broadly, so each card names the control to review before turning automation on for a production application.

Accidental deletion through prune

With prune enabled, Argo CD deletes live resources that no longer appear in the Git source, so a renamed file, a moved path or a bad merge can remove workloads and their data. Argo CD only prunes when prune is set to true, which makes it the first setting to review per application. Check the sync policy on each application and keep prune off for stateful workloads until the team has tested how removals appear in a dry run.

Emptied applications blocked by allowEmpty

If a source path becomes empty, for example after a failed render or an accidental directory removal, a prune could leave the application with no resources. Argo CD blocks that sync unless allowEmpty is set to true, which is a protection to keep rather than switch off. Confirm that allowEmpty is false on every automated application and that teams know a deliberate empty state requires a manual decision.

Self-heal reverting emergency fixes

With selfHeal enabled, Argo CD restores any manual change to the cluster that differs from Git, so a hotfix applied with kubectl during an incident can be undone within seconds. The default self-heal timeout is 5 seconds. Agree on an emergency procedure that commits the fix to Git first or pauses automation for the affected application, and document who may do that.

Repo-server running Helm and Kustomize

The repo-server renders Helm and Kustomize on repository content, so a malicious or careless chart, or a Kustomize file that reads files outside its directory, can affect what gets applied. Automated sync makes that rendered output reach the cluster without review. Limit which repositories are registered, restrict out-of-tree file access and review the security documentation before connecting repositories that outside parties can change.

RBAC that limits who changes the Git source

Automation trusts whatever the Git source contains, so anyone who can push to the tracked branch can change production without going through Argo CD. Restrict write access to the configuration repository with branch protection and required reviews, and limit who can edit Applications and Projects in Argo CD. Since 3.0, update and delete RBAC applies only to the application itself, so confirm the policy in each Project reflects that scope.

Retries that repeat a failing sync

Automated sync does not retry a failed sync against the same commit and parameters, so a transient error can leave an application failed until the next commit or a manual action. The reconciliation check runs every 120 seconds plus up to 60 seconds of jitter by default. Set alerts on failed and OutOfSync states, and confirm that someone is notified when automation stops acting.

Questions teams ask before enabling automated sync

What drives the effort to enable automated sync?

The effort depends mostly on how well your current deployments match what Git says they should be. Teams with clean, fully declarative applications and few manual changes in clusters usually need less work than teams where engineers patch live objects, rely on Helm hooks, or keep secrets outside Git. Other drivers include the number of applications, how many clusters they target, whether resources are shared across teams, and how many environments must be proven before production. Ask any partner to inventory drift, sync history and ownership of each application before agreeing a scope, because that inventory sets the size of the staged rollout.

Can our own team enable automated sync without a partner?

Yes, if the team already runs Argo CD, understands its sync options and can test changes in a non-production cluster first. The settings themselves are small, but the risk sits in the surrounding work: deciding which applications may prune, confirming that empty source paths will not wipe live resources, and checking that no one depends on manual hotfixes. A partner adds value when the team lacks capacity for that review, or when the change must be documented as evidence for an audit. Either way, the decision should be recorded in your change process before production is switched on.

How long does a staged rollout take?

No general duration applies, because the time depends on application count, the criticality of each workload, and how many environments must pass before production. A reasonable plan starts with one non-production application that has no manual drift, enables automated sync with prune and self-heal turned off, observes the results, and then widens the scope one group at a time. Ask for the rollout plan in writing, including the groups, the exit criteria for each stage and the people who approve each step, so the schedule reflects your environments rather than a generic estimate.

What does the work need from our team?

Expect to supply people who own each application, access to the Git repositories and the Argo CD instance, and a non-production cluster that mirrors production closely enough to be useful. Application owners must confirm which manual changes are intentional, and platform engineers must agree on prune and allowEmpty behavior. Your change approvers should review the rollout gates. Plan for these people to be available during each stage, since most problems appear only when a real sync or a real cluster change happens.

How do we recover when rollback is unavailable?

With automated sync enabled, Argo CD does not offer its usual rollback action, so recovery moves to Git. The safe pattern is to revert the offending commit in the source repository, let Argo CD sync that revert, and confirm the cluster state matches the reverted manifests. Teams should also keep a documented procedure for pausing automation on a single application by disabling its automated sync policy, and for restoring a resource that was pruned, usually from a backup or from the previous commit. Test this procedure during the rollout, not during an incident.

What should a quote for this work cover?

A written quote should follow from a written scope that names the applications in each rollout group, the Argo CD version and the clusters involved, and the settings to be enabled for each group. Ask for the assumptions about your environment, such as access, test clusters and named approvers, and for what is one-time work (inventory, configuration, testing and documentation) versus recurring work (monitoring, reviews and upgrades). Also ask how exceptions are handled, which applications stay manual, and what evidence the deliverables include for your change management reviews.

Does automated sync remove resources that someone else deployed?

It can, when prune is enabled and the resource is tracked by the application but missing from Git. Argo CD does not prune anything unless prune is set to true, so the safest starting point is to leave prune off, review what would be removed, and enable it only for applications where Git holds the full desired state. Confirm how your team labels and tracks resources before enabling prune, because resources created outside Git are not affected by the application's sync unless they are part of its managed set.

Limits to confirm in your environment before turning automation on

Automated sync changes who makes production changes, so the settings below need checking against your own Argo CD version, cluster load and change policy. Confirm each one with your own tests and the vendor documentation before enabling automation on a production application.

Version and settings match the guide

Confirm that your Argo CD version and the keys you set match the current automated sync guide, since defaults and behavior can change between minor releases. Patch releases only reach the three most recent minor versions, so an older line may stop receiving fixes. Check the exact syncPolicy block your version accepts in a staging cluster before copying it into production manifests.

Reconciliation interval under load

The default check interval is 120 seconds plus up to 60 seconds of jitter, set through timeout.reconciliation in argocd-cm. Measure how long a full reconciliation takes on your largest instance, because a busy controller can delay the moment drift is corrected. Test whether a shorter or longer interval changes repo-server and API load before you tune it.

Applications that must never auto-prune

Prune removes live resources once they disappear from Git, which can delete stateful data stores, persistent volume claims, or resources created by other tools. Build an explicit list of applications that run with prune disabled, and review any Application that owns databases, message brokers or shared namespaces. Record the owner who approves each exception so the list stays current.

Self-heal and manual fixes

With selfHeal on, Argo CD reverts manual changes made during an incident, such as a scaled deployment or a hotfixed config map, within seconds of detection. Agree with on-call engineers how emergency changes are made, whether through Git, a paused sync, or a documented exception. Test the incident runbook in a non-production cluster before enabling self-heal on production.

Rollback and recovery procedure

Automated sync disables the rollback action in the UI and CLI, so recovery depends on reverting the commit in Git and letting Argo CD apply it. Confirm that your Git hosting permits fast revert, that protected branches allow the revert workflow, and that engineers can run it under pressure. Practice one full revert on a test application before you rely on it.

Change management policy alignment

Your change policy may require a named approver, a ticket, or a separation between authoring and deploying a change. Map each automated deployment path to the approval evidence your policy expects, and decide whether Git approval, a pull request record, or a sync log will serve as that evidence. Confirm this with the people who own change control before automation goes live.

Why rollback is unavailable once automation is on and what replaces it

Once automated sync is enabled, Argo CD's rollback action is no longer available, so recovery has to happen in Git. Automated sync disables rollback, which means the controller always moves the cluster toward the newest commit on the tracked branch. The working recovery path is to revert the bad commit (or push a corrected one), let the controller detect the change, and confirm that the application returns to Synced and Healthy. Before go-live, the team should rehearse this on a non-production application and time how long a revert takes from merge to a healthy cluster, because that interval is the real recovery window for the change.

Recovery also depends on knowing which revision was last known good. Argo CD keeps the revision history of each application, so the reader should confirm where that history is visible in their setup and who is allowed to read it during an incident. Protected branches, required reviews and a tagged release pointer for each environment give the on-call engineer a fixed target to revert to. Teams that promote by tag rather than by branch head can also pin the application to that tag while the revert is prepared, which keeps the fix and the rollback target separate from whatever is currently at the head of the branch.

The trade-off is speed against manual control. Automation shortens the path from merge to cluster, but every merged commit reaches production without a second human decision. Where the change process requires an explicit approval step, pair the settings in this topic with sync windows that block syncs during freezes, and with Notifications that alert the team when a sync fails or an application turns Degraded. Sync windows give a gate by schedule, and notifications give a human a reason to act. Confirm with your change manager which environments need a gate and which can accept automatic revert-driven recovery.

What a DeployOpen engagement covers for sync policy

A sync policy engagement reviews how far Argo CD is allowed to act without a person, then tests and documents that decision. The cards below are the work streams we agree in writing before any change is made, and each one feeds the next so that automation is enabled deliberately rather than all at once.

Reviewing sync policy per application

We inventory every Application and record whether it uses automated sync, and which of prune, allowEmpty and selfHeal are set. Production services that hold stateful resources usually need a different answer from stateless front ends, so each application gets its own decision. The output is a table of current and proposed settings, with the reason for each choice. Check that no application relies on prune being on by default, because Argo CD only removes resources when prune is true.

Staging the enablement

We enable automation first in a non-production cluster, then in one low-risk production application, then widen the scope in steps. Each stage has a defined observation period and a rollback owner. Automated sync runs only for OutOfSync applications and does not retry a failed sync against the same commit and parameters, so the staging plan must include how failures will be found and retried by a person.

Setting RBAC and admin controls

We define which roles may change sync settings in an Application or AppProject, and who may trigger a manual sync that overrides automation. The built-in admin user is limited to initial setup and is disabled with admin.enabled set to false once SSO or local users are in place. Confirm that SSO group mapping and project boundaries match the teams that own each application.

Testing drift and prune scenarios

We run scripted tests on a non-production cluster: a manual edit to a managed Deployment, removal of a manifest from Git, an empty source directory, and a failing sync. For each case we record whether selfHeal corrected the drift, whether prune removed the resource, and whether allowEmpty was needed. Test results decide which settings reach production, and they become the evidence for the change process.

Tuning the reconciliation interval

We review the timeout.reconciliation value in argocd-cm, which defaults to 120 seconds plus up to 60 seconds of jitter, against the number of applications and the cost of repository polling in your environment. Changing the interval affects how quickly drift is noticed and how much load falls on the repo-server. We document the chosen value and the reason it was chosen, so operators know what delay to expect.

Documenting recovery steps

Because rollback is disabled once automated sync is on, recovery becomes a Git operation: revert the commit, let Argo CD sync, and verify the cluster state. We write runbooks for reverting a bad commit, pausing automation on one application, forcing a manual sync, and restoring a pruned resource from backup. Each runbook names the owner and the command or UI path, and it is tested before it is needed.

How DeployOpen scopes and supports Argo CD sync policy

DeployOpen plans how far Argo CD acts on its own for each application before any automation is switched on. The work covers prune, allowEmpty, self-heal and the reconciliation settings, written into a fixed scope and deployed in the client's own clusters and infrastructure.

How we scope

We inventory which applications can safely auto-sync and which need manual promotion for Argo CD sync policy.
We document prune and allowEmpty decisions per application, including what happens when a manifest is removed from Git.
Engagements are fixed-scope, with the sync policy matrix and rollback approach agreed in writing before work starts.

How we build

We configure automated sync, selfHeal and retry settings in Application manifests and ProjectS per team.
We tune timeout.reconciliation in argocd-cm and test drift behavior against a staging cluster first.
We test manual cluster changes, failed syncs and empty-source scenarios to confirm the configured behavior matches the design.

How we hand over

We deliver the sync policy as code in your Git repository, with reviewed change history and ownership noted.
We write a runbook covering rollback without automation, pausing auto-sync during incidents and re-enabling it safely.
We walk your platform and on-call teams through drift alerts, failed sync triage and the deletion safeguards in place.

How we support

Ongoing support, upgrades and continuous testing are available as a retainer after handover.
We review sync policy when Argo CD minor releases change behavior, checking the release notes before upgrading.
We confirm current supported patch lines with you before each upgrade window, since the project supports only the three most recent minor versions.