Argo CD Notifications for Slack, email and PagerDuty

Notification options and when each fits

This table compares the Argo CD Notifications building blocks, from triggers and templates to per-service configuration and subscription annotations on Applications and AppProjects. Read each row against your team count and cluster count to see where a simple setup stops being enough. The main takeaway is that subscriptions and destinations, not the trigger logic, usually decide how hard the setup is to govern.

Setting up Argo CD Notifications step by step

This sequence takes a running Argo CD installation from a version check to a tested alert on a failed sync, with each service credential, template and subscription confirmed before the next step builds on it.

1. Confirm the Argo CD version and notifications controller

   Before changing anything, confirm which Argo CD version is installed and that the notifications controller is running in the argocd namespace. Run the version check with the argocd CLI or read the image tag on the argocd-server deployment, then check that the notifications controller pod is ready. Compare the version against the release line you plan to stay on, because the three most recent minor versions receive patch releases and the configuration keys can differ between releases. Confirm the target version with your release notes before you copy examples from any documentation. Done means you have a recorded version, a healthy notifications pod, and a named owner for the alert channels.

2. Create service credentials as Kubernetes Secrets

   Create one Kubernetes Secret for each destination, such as a Slack bot token, an SMTP username and password, and a PagerDuty integration key. Keep these in the argocd namespace, restrict read access with RBAC, and never place tokens in argocd-notifications-cm or in Git. Reference the Secret keys from the notifications configuration using the $secret-name:key pattern so the controller resolves them at runtime. Verify by listing the Secrets and confirming each key exists with the expected name, without printing the values into a terminal log or ticket.

3. Configure services and templates in argocd-notifications-cm

   Edit the argocd-notifications-cm ConfigMap to declare each service, such as slack, email and pagerduty, and reference the credentials created in the previous step. Then add templates that define the message body for a failed sync, a degraded application and a successful deployment. Keep templates short and include the application name, revision, sync status and a link back to the Argo CD UI. Check the syntax by applying the ConfigMap to a non-production cluster and reading the notifications controller logs for parse errors. Done means the controller starts without configuration errors for each service.

4. Define triggers for failed and degraded syncs

   Add triggers to argocd-notifications-cm that fire on the conditions you care about. The usual choices are a sync that ends in a failed phase, and an application whose health becomes Degraded. Each trigger has a when condition written against application status fields and a list of templates to send. Keep the first set narrow so you can read every message that fires during testing. Verify the triggers by reviewing the rendered condition expressions with your team and confirming they match the health and sync values shown in the Argo CD UI for a deliberately broken test application.

5. Add subscription annotations to a test application

   Pick one non-production Application and add a subscription annotation for each trigger and service pair you want it to use, following the notifications.argoproj.io annotation format in the official documentation. Include the destination name or channel for each service. Subscriptions set on the Application apply only to that Application, so this confirms routing before you scale it out. Verify by checking the annotations with kubectl or the UI and confirming the controller logs show the subscription being picked up without warnings about unknown triggers or services.

6. Add subscriptions to a project for inherited routing

   Set subscription annotations on an AppProject so that every Application in that project inherits the same destinations, which keeps team routing in one place. Confirm with your team which project owns each channel, because a single project subscription can fan out to many applications. Check that the project annotation applies to the test application without duplicating the application-level subscription. Done means the test application receives its alerts from the project-level subscription, and you have recorded which channels each project feeds.

7. Test a failed sync and confirm every channel

   Trigger a controlled failure in the test application, for example by pointing it at a manifest that references a missing resource in a disposable namespace. Watch the sync fail in the Argo CD UI, then confirm one message arrives in each configured channel with the expected application name, revision and status. Correct the manifest and confirm that the recovery produces the successful deployment template. Record the test result and the exact trigger and template names used. Only after this passes should you expand subscriptions to production applications, and keep the failure test as a repeatable check for future upgrades.

Writing triggers and templates that fire only on real problems

Securing service credentials and notification content

Notifications touch three kinds of sensitive material: service credentials that let Argo CD post to Slack, send email and page on-call staff, the configuration that decides who gets told what, and the sync details that end up in messages. The cards below cover where each one lives, who can change it, what goes into a message, and how changes are traced.

Questions teams ask before setting up Argo CD notifications

Official Argo CD sources to read next