⚓ Argo CD Master Guide: Types of Hook Phases and How to Use Them Perfectly

Jun 21, 2026

—

Hello! When practicing GitOps in a Kubernetes environment, you might often wonder, “Can’t I run DB migrations before the application is deployed?” or “Is it possible to send notifications to Slack after deployment is finished?”

Argo CD Resource Hooks perfectly solve these requirements. Today, we will delve into the types of Phases (stages) when these Hooks are executed and their practical application methods. 🛠️

1. ❓ What is an Argo CD Hook?

Basically, Argo CD’s role is to ‘apply’ manifests from Git to the cluster. However, by using Hooks, you can control specific resources to be executed at specific points during the synchronization (Sync) process.

They are primarily used by adding annotations to Job or Pod resources, and are used to finely tune the deployment lifecycle.

2. ⏳ 5 Types of Hook Phases

Argo CD has a total of 5 main Hook Phases. Each phase is triggered at a specific point in the synchronization process.

① PreSync (Before Synchronization)

Executed before the synchronization operation begins, i.e., before the actual application resources are applied to the cluster.

Purpose: Database schema migration, pre-validation of configuration files.
Characteristic: The next phase proceeds only if the Hook in this phase succeeds. If it fails, synchronization is aborted.

② Sync (During Synchronization)

Executed concurrently with the application resources being applied.

Purpose: Complex deployment orchestration.
Characteristic: Created along with regular resources.

③ PostSync (After Synchronization)

Executed after all resources have been successfully deployed and are in a Healthy state.

Purpose: Health checks, external service notifications (Slack/Teams), running load tests.

④ SyncFail (On Synchronization Failure)

Triggered when an error occurs during the synchronization process, leading to failure.

Purpose: Error log collection, cleanup operations, sending failure notifications.

⑤ Skip (Bypass)

Instructs Argo CD to skip the synchronization of the corresponding resource. (Mainly used during debugging)

3. 💻 Practical Code: Applying Hooks

To apply a Hook, you need to add argocd.argoproj.io/hook to the metadata.annotations section of your manifest.

📜 Example: DB Migration (PreSync Job)

YAML

apiVersion: batch/v1
kind: Job
metadata:
  generateName: schema-migrate-
  annotations:
    # 1. Defines the Hook phase. (Executes before synchronization) 🛡️
    argocd.argoproj.io/hook: PreSync
    # 2. Set resource deletion policy after Hook execution (delete on success) 🗑️
    argocd.argoproj.io/hook-delete-policy: HookSucceeded
spec:
  template:
    spec:
      containers:
      - name: migrate
        image: my-db-migrator:v1.0.0
        command: ["/app/migrate.sh"]
      restartPolicy: Never
  backoffLimit: 2

📜 Example: Deployment Completion Notification (PostSync Pod)

YAML

apiVersion: v1
kind: Pod
metadata:
  generateName: slack-notifier-
  annotations:
    # Executes after all resources are successfully deployed. 📢
    argocd.argoproj.io/hook: PostSync
    # Deletes 5 minutes after execution completion, regardless of the result.
    argocd.argoproj.io/hook-delete-policy: BeforeHookCreation
spec:
  containers:
  - name: notify
    image: curlimages/curl
    command: ["curl", "-X", "POST", "-d", "payload={'text': '배포 완료!'}", "https://hooks.slack.com/..."]
  restartPolicy: Never

4. 🧹 Hook Deletion Policy (hook-delete-policy)

It is also very important when to delete resources created by Hooks (mainly Jobs). If not deleted, completed Jobs will continue to accumulate in the cluster.

Policy Type	Description
HookSucceeded	Immediately deletes the Hook upon successful completion (most recommended)
HookFailed	Deletes the Hook only when it fails (can be inconvenient for debugging)
BeforeHookCreation	Deletes the previous Hook just before a new Hook is created

—

5. ⚠️ Precautions and Tips

Maintain Idempotency: PreSync Jobs, etc., can be executed multiple times, so the results should always be the same or safe for duplicate executions.
Resource Names: It is recommended to use generateName instead of name for Hook resources. This creates a unique name for each synchronization, preventing conflicts.
Combination with Sync Waves: Using it with argocd.argoproj.io/sync-wave allows for more precise order control. (e.g., DB deployment in Wave 1, migration execution in PreSync of Wave 2)

📝 Summary Table

Phase	Execution Time	Key Use Cases
PreSync	Before resource deployment	DB migration, pre-checks
Sync	Concurrent with resource deployment	Executing parallel tasks
PostSync	After deployment completion (Healthy)	Sending notifications, integration tests
SyncFail	Upon error occurrence	Recovery scripts, failure notifications

—

💡 Conclusion

Understanding Argo CD’s Hook Phases allows you to utilize it not just as a simple deployment tool, but as a powerful Workflow Engine. Especially, DB migration and automated deployment notifications are essential elements that enhance productivity in practice.

Try applying the concepts discussed today to your projects and build a safer and smarter deployment pipeline! 🎯