The commit is merged. You click Refresh, the Application stays Synced on the old revision. You click Sync, and it deploys something anyway — not necessarily what you just pushed.
The two buttons sit next to each other in the UI and carry similar names. They do not do the same thing, they do not act on the same data, and one of them writes nothing to the cluster at all. The third button, hiding in the first one’s dropdown, exists precisely because the first is not always enough.
Refresh recomputes, sync writes
A refresh is a read operation. Argo CD re-reads the desired state — the manifests generated from the source — and the live state through the Kubernetes API, recomputes the diff, and updates the Synced / OutOfSync status. Nothing is applied to the cluster.
A sync is a write operation. It is the one that runs kubectl apply (or replace, or apply --server-side, depending on the sync options), runs hooks and waves, and is recorded in the Application’s history.
On the CLI the distinction is visible in the commands themselves: argocd app get my-app --refresh refreshes application data while retrieving it, whereas argocd app sync my-app starts an operation.
# Read-only: recompute the diff, write nothing to the cluster
argocd app get my-app --refresh
# Read-only, and also invalidate the target manifests cache
argocd app get my-app --hard-refresh
# Write: run the sync operation
argocd app sync my-app
The practical consequence is simple: a refresh cannot break anything, and it cannot fix anything either. An OutOfSync obtained after a refresh is a diagnosis, not the beginning of a fix.
The cache that explains the hard refresh
Which leaves the question that brings everyone here: why does a refresh sometimes fail to see a change that is genuinely in the repository?
Because Argo CD does not regenerate manifests on every refresh. The argocd-repo-server caches generated manifests — 24 hours by default, tunable through --repo-cache-expiration. The assumption behind that cache is explicit in the documentation: manifests only change when the repo changes.
That assumption is wrong in at least two common situations. A remote Kustomize base can move without the Application’s own repository changing. And a Helm chart modified without bumping its version number yields different manifests at an identical URL and version. In both cases, the normal refresh correctly observes that the revision has not changed, and serves the cache.
This is what the hard refresh unlocks: it refreshes application data as well as the target manifests cache. The CLI documentation words --hard-refresh exactly that way.
Two more cases justify the button, and they are documented in their own right. The first is the Manifest generation error (cached) error: when manifest generation fails, the error message is cached to avoid runaway retries. A hard refresh ignores the cached error and can get past a transient incident — but if there is an ongoing cause it will not help, and the documentation then points at the repo-server logs, searching for the app name. The second case is developing a config management plugin: plugin errors are cached by the repo-server in Redis, and restarting the repo-server pod does not clear that cache. That is the natural reflex, and it does not work.
Conversely, if you catch yourself hard-refreshing a given Application routinely, that is no longer troubleshooting: it is a sign that a 24-hour cache does not suit that source. Lowering --repo-cache-expiration is the intended answer — the documentation suggests one hour in low-volume environments, while warning that too low a value negates the benefit of caching.
What triggers a refresh without you clicking
Three mechanisms cause a refresh, and none of them causes a sync.
The periodic loop. The application controller re-reads the source at a regular interval. The value is timeout.reconciliation in the argocd-cm ConfigMap, 120 seconds by default, plus a timeout.reconciliation.jitter defaulting to one minute. Hence the “every three minutes” you read elsewhere in the documentation: that is the upper bound. The jitter is not decorative — it spreads refreshes out so that not every Application hits the repo-server at once.
Resource changes. By default, an Application is refreshed every time a resource belonging to it changes. That is also why chatty controllers can keep an application controller permanently busy, and what ignoreResourceUpdates exists to calm down.
The webhook. A Git webhook pointing at /api/webhook removes the polling delay. What it triggers is a refresh, not a deployment — the documentation says so explicitly when justifying that the shared secret is optional: an unauthenticated event can only cause a refresh, a process that already occurs at three-minute intervals on its own. The deployment only follows if an automated policy sits behind it.
One detail to know before wiring the webhook: the handler does not differentiate branch events from tag events sharing the same name. A push to branch x refreshes an Application pointing at refs/tags/x in the same repo.
What an automated sync does, and does not redo
When spec.syncPolicy.automated is on, the sync follows a refresh — but not systematically, and the documented rules explain most “why won’t it redeploy” cases.
An automated sync is only attempted if the Application is OutOfSync; in a Synced or error state, nothing starts. More importantly, it is attempted only once per unique combination of commit SHA and application parameters. If the most recent successful sync in history already used that pair, there is no second attempt — unless selfHeal is enabled, in which case the sync is retried after the self-heal timeout, five seconds by default. And an automated sync that failed on a given pair is not reattempted on that same pair.
This is where the cache and the automation meet in a clean failure mode: a chart modified without a version change produces neither a new revision nor new parameters. Nothing moves, and nothing reports it. The hard refresh is then the only gesture that puts the system back in motion.
# The reconciliation cadence, in argocd-cm
# timeout.reconciliation: 120s
# timeout.reconciliation.jitter: 60s
kubectl -n argocd get cm argocd-cm -o yaml | grep -A1 'timeout.reconciliation'
One last surprise: a rollback cannot be performed against an Application with automated sync enabled. This is not an arbitrary limit, it is a direct consequence of the model — the desired state is Git, and going back without going through Git would immediately put the controller at odds with itself. Rolling back a GitOps system is a commit, not a button, which is far from obvious when you come from kubectl rollout undo.
For the reconciliation mechanics themselves: declarative deployment with ArgoCD, and the French reading path la chaîne CI/CD for where all this sits in the pipeline.