GitOps sync

The "sync" pipeline is the core feature of Argo CD. This page traces the path from a Git push (or a manual argocd app sync) through to resources applied to the destination cluster.

Stages

graph TD
    A[Trigger: webhook, manual sync, schedule] --> B[Refresh Application]
    B --> C[Repo server: GenerateManifests]
    C --> D[Compare against live state]
    D --> E{In sync?}
    E -- No --> F[Sync operation]
    F --> G[PreSync hooks]
    G --> H[Apply resources]
    H --> I[Wait for healthy]
    I --> J[PostSync hooks]
    J --> K[Status: Synced + Healthy]
    E -- Yes --> K
    F --> SF[SyncFail hook on failure]

Triggers

Refreshes are triggered by:

• Polling — every --app-resync seconds (default ~3 min) the application controller refreshes each Application. --app-hard-resync does the same but skips caches.
• Webhooks — util/webhook/webhook.go registers handlers for GitHub, GitLab, Bitbucket Server/Cloud, Bitbucket Cloud, Azure DevOps, and Gitea. On a push event matching an Application's source repo, the API server requests an immediate refresh.
• Manual — argocd app refresh, argocd app sync, or the UI "Refresh"/"Sync" buttons. The CLI hits the gRPC ApplicationService.Sync / ApplicationService.Get(refresh=true) methods on the API server.

The application controller's queue is fed by all three paths and processed by controller/appcontroller.go.

Comparison (refresh)

controller/state.go (~54 KB) implements CompareAppState, which:

1. Resolves the source revision (Git SHA, Helm chart version, OCI digest).
2. Asks the repo server for rendered manifests via reposerver/apiclient/.
3. Reads live state from the cluster cache (util/settings/cluster_informer.go).
4. Normalizes both sides through util/argo/normalizers/ — strip metadata.managedFields, ignore well-known noise (corev1 known-types, JSON pointers from ignoreDifferences).
5. Computes diffs via the embedded gitops-engine.
6. Builds the per-resource SyncStatus and the application-level health using the per-resource health checks (built-ins from gitops-engine, custom Lua from resource_customizations/).
7. Persists the result to Redis (so the API server can answer UI queries cheaply).

Diff modes are controlled by the --server-side-diff-enabled flag and per-app argocd.argoproj.io/compare-options annotations.

Sync operation

controller/sync.go is the operation orchestrator. The high-level flow:

1. Compose the apply manifest set — pruned + non-pruned resources, hooks separated by phase.
2. Wave ordering — sort by argocd.argoproj.io/sync-wave, then by Kind ordering rules from gitops-engine (namespaces first, CRDs early, etc.). Helpers in controller/sort_delete.go.
3. PreSync hooks — run hooks tagged PreSync (controller/hook.go), wait for Succeeded/Failed.
4. Sync hooks + main apply — apply the rest in waves; resources tagged Sync are hooks that run during this phase.
5. Wait for healthy — controller/health.go aggregates per-resource health.
6. PostSync hooks — run after success.
7. SyncFail hooks — run if any phase fails.

Knobs:

• spec.syncPolicy.automated — enables auto-sync on drift.
• spec.syncPolicy.automated.prune — delete resources removed from Git.
• spec.syncPolicy.automated.selfHeal — re-apply if the cluster drifts. Backoff configured by --self-heal-backoff-* flags.
• spec.syncPolicy.retry — retry policy with exponential backoff.
• spec.syncPolicy.syncOptions — Validate=false, CreateNamespace=true, ServerSideApply=true, Prune=false, etc.
• argocd.argoproj.io/sync-options — same options at resource granularity.

Hooks

controller/hook.go implements the hook lifecycle. A resource becomes a hook if it has the argocd.argoproj.io/hook annotation. Supported phases: PreSync, Sync, PostSync, SyncFail. Deletion policies (HookSucceeded, HookFailed, BeforeHookCreation) are respected. Job-style hooks (Job, Pod, Workflow) are common.

Health and statuses

Argo CD tracks two orthogonal statuses for each Application:

• Sync status — Synced, OutOfSync, Unknown. Computed by controller/state.go.
• Health status — Healthy, Progressing, Degraded, Suspended, Missing, Unknown. Computed by controller/health.go and the gitops-engine health checks. CRDs may ship custom Lua under resource_customizations/.

Audit trail

Each sync operation produces a SyncOperation and OperationState in the Application's status (defined in pkg/apis/application/v1alpha1/types.go). The audit log stores these and emits Kubernetes events through util/argo/audit_logger.go.

Webhooks: enabling instant sync

Configure the upstream Git host to POST to https://<argocd-server>/api/webhook with the appropriate provider header. util/webhook/webhook.go handles authentication via the configured shared secrets in argocd-secret.

See also

• Application controller — the runtime owning this loop.
• Repo server — the manifest renderer.
• Sources and tooling — how individual tools render.
• Manifest hydrator — the optional render-and-commit variant.