Notifications controller

argocd-notifications (binary name) is a controller that watches Applications, evaluates configured triggers against their state, and sends notifications via the Argoproj-Labs notifications-engine.

Purpose

• Notify users on Application events: sync started/succeeded/failed, health degraded, deployment finished, etc.
• Support many delivery backends: Slack, Microsoft Teams, email, webhooks, GitHub status, GitLab, Telegram, Opsgenie, PagerDuty, Mattermost, Rocket.Chat, and more.
• Allow self-service subscriptions through Application annotations.
• Ship a curated catalog of built-in triggers and templates.

Where it lives

Path	Purpose
cmd/argocd-notification/commands/	Binary entry point.
notification_controller/	Top-level package wiring the engine to Argo CD primitives.
notification_controller/controller.go (and friends)	Reconciliation loop.
util/notification/argocd/	Argo CD-specific glue (App state lookups).
util/notification/expression/	Expression evaluators for triggers (CEL/expr).
util/notification/k8s/	ConfigMap/Secret loaders for argocd-notifications-cm / argocd-notifications-secret.
util/notification/settings/	Settings/templates parsing.
notifications_catalog/	Out-of-the-box triggers (triggers/) and templates (templates/).
notifications_catalog/install.yaml	Bundled ConfigMap that installs the catalog into a cluster.
cmd/argocd/commands/admin/notifications.go	CLI surface for testing triggers/templates locally.

How it works

graph LR
    Watch[App informer] --> Eval[Evaluate triggers per app]
    Eval --> Match{Match?}
    Match -->|yes| Tmpl[Render template]
    Tmpl --> Send[Send via service]
    Send --> SlackEt[(Slack/Email/Webhook/etc.)]
    Eval --> SubAnno[Read app subscription annotations]

A "trigger" is a CEL/expr predicate over the Application object. A "template" turns the matched event into a payload (text, JSON, or service-specific structure). Subscriptions are stored in two places:

• Cluster-wide config in argocd-notifications-cm.
• Self-service annotations on the Application itself (notifications.argoproj.io/subscribe.<trigger>.<service>: <recipient>).

The controller persists per-app notification state via the notified.notifications.argoproj.io annotation (also referenced as NotifiedAnnotationKey in the ApplicationSet controller, for cross-controller parity).

Catalog

notifications_catalog/triggers/ ships a YAML file per built-in trigger (sync-succeeded, sync-failed, app-health-degraded, app-created, app-deleted, …) and notifications_catalog/templates/ ships rendering templates for each. The CLI command argocd admin notifications (registered in cmd/argocd/commands/admin/notifications.go) lets operators dry-run and lint these locally.

Configuration

Two ConfigMaps and one Secret are the contract:

• argocd-notifications-cm — services, triggers, templates, default subscriptions.
• argocd-notifications-secret — service credentials (Slack tokens, SMTP passwords, …).
• The "self-service notifications" feature, gated by --self-service-notification-enabled, lets Application owners add per-app subscriptions without touching the cluster-wide ConfigMap.

Entry points for modification

• Add a built-in trigger → drop YAML in notifications_catalog/triggers/ and a matching template in notifications_catalog/templates/.
• Wire a new service → contribute to argoproj/notifications-engine; minimal glue may be needed in util/notification/.
• Tweak per-app annotation parsing → util/notification/.

See features/notifications for the user-facing behavior.