> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/argoproj/argo-cd/llms.txt
> Use this file to discover all available pages before exploring further.

# Sync Strategies

> Auto-sync, manual sync, sync waves, and advanced synchronization options

Argo CD provides flexible synchronization strategies to control when and how applications are deployed to your clusters.

## Manual Sync

By default, applications require manual synchronization. When changes are detected in Git, you must explicitly trigger a sync operation.

```bash theme={null}
# Sync application
argocd app sync myapp

# Sync with pruning
argocd app sync myapp --prune

# Force sync (recreate resources)
argocd app sync myapp --force
```

## Automated Sync Policy

Argo CD can automatically sync applications when it detects differences between the desired manifests in Git and the live state in the cluster.

### Enabling Auto-Sync

<CodeGroup>
  ```yaml Application Manifest theme={null}
  spec:
    syncPolicy:
      automated: {}
  ```

  ```bash CLI Command theme={null}
  argocd app set myapp --sync-policy automated
  ```
</CodeGroup>

### Auto-Sync with Enabled Flag

You can explicitly control automated sync using the `enabled` field:

```yaml theme={null}
spec:
  syncPolicy:
    automated:
      enabled: true  # or false to disable
```

<Note>
  Setting `spec.syncPolicy.automated.enabled` to `null` is treated as enabled. When set to `false`, the controller will skip automated sync even if `prune`, `selfHeal`, and `allowEmpty` are configured.
</Note>

## Automatic Pruning

By default, automated sync will not delete resources when they are removed from Git. Enable automatic pruning to delete resources:

```yaml theme={null}
spec:
  syncPolicy:
    automated:
      prune: true
```

<Warning>
  Automatic pruning will delete resources from your cluster when they're removed from Git. Use with caution.
</Warning>

### Allow Empty Resources

Prevents errors when there are no target resources:

```yaml theme={null}
spec:
  syncPolicy:
    automated:
      prune: true
      allowEmpty: true
```

## Automatic Self-Healing

When enabled, Argo CD will automatically revert manual changes made to the live cluster:

```yaml theme={null}
spec:
  syncPolicy:
    automated:
      selfHeal: true
```

<Info>
  By default, changes made to the live cluster will not trigger automated sync. Self-heal ensures your cluster state always matches Git.
</Info>

<Note>
  Disabling self-heal does not guarantee that live cluster changes will persist in multi-source applications. Changes in one source can trigger autosync even if another remains unchanged.
</Note>

## Sync Options

Fine-tune sync behavior with sync options:

```yaml theme={null}
spec:
  syncPolicy:
    syncOptions:
      # Disable kubectl validation
      - Validate=false
      
      # Create namespace if it doesn't exist
      - CreateNamespace=true
      
      # Set prune propagation policy
      - PrunePropagationPolicy=foreground  # or background, orphan
      
      # Prune resources as final wave
      - PruneLast=true
      
      # Respect ignoreDifferences during sync
      - RespectIgnoreDifferences=true
      
      # Only sync out-of-sync resources
      - ApplyOutOfSyncOnly=true
      
      # Use kubectl replace instead of apply
      - Replace=true
      
      # Skip dry run on missing resources
      - SkipDryRunOnMissingResource=true
```

### Managed Namespace Metadata

When using `CreateNamespace=true`, you can set metadata on the namespace:

```yaml theme={null}
spec:
  syncPolicy:
    syncOptions:
      - CreateNamespace=true
    managedNamespaceMetadata:
      labels:
        environment: production
        team: platform
      annotations:
        monitoring: enabled
```

## Sync Waves

Sync waves allow you to control the order in which resources are applied using the `argocd.argoproj.io/sync-wave` annotation.

### How Waves Work

<Steps>
  <Step title="Resources are ordered">
    All resources are ordered by their wave number (lowest to highest)
  </Step>

  <Step title="Sequential application">
    Resources in each wave are applied sequentially
  </Step>

  <Step title="Health check">
    Argo CD waits for all resources in a wave to be healthy before proceeding
  </Step>
</Steps>

### Wave Examples

```yaml Wave -1: Database Migration theme={null}
apiVersion: batch/v1
kind: Job
metadata:
  name: db-migrate
  annotations:
    argocd.argoproj.io/sync-wave: "-1"
spec:
  template:
    spec:
      containers:
        - name: migrate
          image: flyway:latest
          # migration command
```

```yaml Wave 0: ConfigMaps and Secrets (default) theme={null}
apiVersion: v1
kind: ConfigMap
metadata:
  name: app-config
  # No annotation = wave 0
data:
  config.yaml: |
    # configuration
```

```yaml Wave 1: Deployments theme={null}
apiVersion: apps/v1
kind: Deployment
metadata:
  name: backend
  annotations:
    argocd.argoproj.io/sync-wave: "1"
spec:
  # deployment spec
```

```yaml Wave 2: Services theme={null}
apiVersion: v1
kind: Service
metadata:
  name: backend-service
  annotations:
    argocd.argoproj.io/sync-wave: "2"
spec:
  # service spec
```

<Info>
  Waves are assigned to wave 0 by default. Waves can be negative, allowing you to create resources that run before everything else.
</Info>

## Sync Phases (Hooks)

Hooks allow you to run resources at specific points in the sync lifecycle:

| Hook Type    | Description                                       |
| ------------ | ------------------------------------------------- |
| `PreSync`    | Executes before the application of manifests      |
| `Sync`       | Executes at the same time as manifest application |
| `PostSync`   | Executes after all resources are healthy          |
| `SyncFail`   | Executes when the sync operation fails            |
| `Skip`       | Skips the resource during sync                    |
| `PreDelete`  | Executes before Application deletion              |
| `PostDelete` | Executes after Application resources are deleted  |

### Hook Example

```yaml theme={null}
apiVersion: batch/v1
kind: Job
metadata:
  name: post-deploy-notification
  annotations:
    argocd.argoproj.io/hook: PostSync
    argocd.argoproj.io/hook-delete-policy: HookSucceeded
spec:
  template:
    spec:
      containers:
        - name: notify
          image: curlimages/curl
          command:
            - curl
            - '-X'
            - POST
            - 'https://hooks.slack.com/services/...'
      restartPolicy: Never
```

### Hook Deletion Policies

| Policy               | Description                                  |
| -------------------- | -------------------------------------------- |
| `HookSucceeded`      | Delete after successful execution            |
| `HookFailed`         | Delete after failed execution                |
| `BeforeHookCreation` | Delete existing hook before creating new one |

## Combining Waves and Hooks

You can combine sync waves with hooks for fine-grained control:

```yaml theme={null}
apiVersion: batch/v1
kind: Job
metadata:
  name: db-schema-update
  annotations:
    argocd.argoproj.io/hook: PreSync
    argocd.argoproj.io/sync-wave: "-1"
    argocd.argoproj.io/hook-delete-policy: HookSucceeded
spec:
  # Job spec
```

Argo CD orders resources by:

1. **Phase** (PreSync, Sync, PostSync)
2. **Wave** (lowest to highest)
3. **Kind** (namespaces first, then other resources)
4. **Name** (alphabetically)

## Retry Policy

Configure automatic retry on sync failure:

```yaml theme={null}
spec:
  syncPolicy:
    retry:
      limit: 5  # Number of retry attempts
      backoff:
        duration: 5s      # Initial backoff duration
        factor: 2         # Multiplier for each retry
        maxDuration: 3m   # Maximum backoff duration
```

### Refresh on Retry

Automatically refresh application on new revisions during retries:

```yaml theme={null}
spec:
  syncPolicy:
    retry:
      refresh: true
```

## Automated Sync Semantics

<AccordionGroup>
  <Accordion title="When does automated sync trigger?">
    * Only when the application is `OutOfSync`
    * Applications in `Synced` or error states will not auto-sync
    * One sync per unique combination of commit SHA and parameters
    * Will not retry if a previous sync failed for the same commit
  </Accordion>

  <Accordion title="Self-heal behavior">
    * When `selfHeal: true`, sync will retry after self-heal timeout (default: 5 seconds)
    * Timeout is controlled by `--self-heal-timeout-seconds` flag
  </Accordion>

  <Accordion title="Sync frequency">
    * Determined by `timeout.reconciliation` in `argocd-cm` ConfigMap
    * Default: 120 seconds with 60 seconds jitter (max 3 minutes)
  </Accordion>

  <Accordion title="Limitations">
    * Rollback cannot be performed on applications with automated sync enabled
  </Accordion>
</AccordionGroup>

## ApplicationSet Auto-Sync Toggle

For ApplicationSet-managed applications, toggling auto-sync requires special handling. See the [ApplicationSet documentation](/features/applicationsets) for details on controlling resource modification.

<Card title="Related Resources" icon="book">
  * [Sync Phases and Waves Documentation](https://argo-cd.readthedocs.io/en/stable/user-guide/sync-waves/)
  * [Resource Hooks](https://argo-cd.readthedocs.io/en/stable/user-guide/resource_hooks/)
  * [Sync Options](https://argo-cd.readthedocs.io/en/stable/user-guide/sync-options/)
</Card>