Triggers

Triggers are responsible for performing actions when a new container version is found.

Triggers are enabled using environment variables.

DD_ACTION_{{ trigger_type }}_{{ trigger_name }}_{{ trigger_configuration_item }}=XXX
DD_NOTIFICATION_{{ trigger_type }}_{{ trigger_name }}_{{ trigger_configuration_item }}=XXX

Environment variable prefixes

Three prefixes are supported for trigger configuration:

All three prefixes are interchangeable -- they configure the same triggers. Use whichever reads best for your use case: DD_ACTION_* for update-action triggers (Docker, Docker Compose) and DD_NOTIFICATION_* for messaging triggers (Slack, SMTP, Discord, etc.), or use either for any trigger type.

When the same trigger property is set under multiple prefixes, the merge priority is DD_NOTIFICATION_* > DD_ACTION_* > DD_TRIGGER_* (highest wins).

Migrating trigger prefixes

The following example shows a typical before/after migration for a Docker + Slack setup.

Before (deprecated DD_TRIGGER_* form):

# .env — legacy form (deprecated in v1.5.0, removed in v1.7.0)
DD_TRIGGER_DOCKER_LOCAL_SOCKETPATH=/var/run/docker.sock
DD_TRIGGER_SLACK_MYSLACK_URL=https://hooks.slack.com/services/T000/B000/xxxx
DD_TRIGGER_SMTP_GMAIL_HOST=smtp.gmail.com
DD_TRIGGER_SMTP_GMAIL_PORT=465

Run the migration (add --dry-run to preview without writing):

drydock config migrate --source trigger

After (canonical prefixes):

# .env — canonical form
# Update-action triggers use DD_ACTION_*
DD_ACTION_DOCKER_LOCAL_SOCKETPATH=/var/run/docker.sock
# Messaging/notification triggers use DD_NOTIFICATION_*
DD_NOTIFICATION_SLACK_MYSLACK_URL=https://hooks.slack.com/services/T000/B000/xxxx
DD_NOTIFICATION_SMTP_GMAIL_HOST=smtp.gmail.com
DD_NOTIFICATION_SMTP_GMAIL_PORT=465

Available triggers

Update actions:

• Docker -- Update containers via the Docker Engine API
• Docker Compose -- Update containers managed by Docker Compose
• Command -- Execute a shell command

Messaging & notifications:

• Apprise -- Multi-provider notification relay
• Discord -- Discord webhook
• Google Chat -- Google Chat webhook
• Gotify -- Gotify push notification
• HTTP -- Generic HTTP request
• IFTTT -- IFTTT webhook
• Kafka -- Apache Kafka topic
• Matrix -- Matrix room message
• Mattermost -- Mattermost webhook
• MQTT -- MQTT topic
• ntfy -- ntfy push notification
• Pushover -- Pushover notification
• Rocket.Chat -- Rocket.Chat webhook
• Slack -- Slack webhook
• SMTP -- Email notification
• Teams -- Microsoft Teams webhook
• Telegram -- Telegram bot message

Common trigger configuration

All implemented triggers, in addition to their specific configuration, also support the following common configuration variables. The table uses DD_NOTIFICATION_{trigger_type}_{trigger_name}_* for notification triggers and DD_ACTION_{trigger_type}_{trigger_name}_* for action triggers (see Environment variable prefixes above). For brevity the rows below show the DD_NOTIFICATION_* form; replace with DD_ACTION_* for Docker, Docker Compose, and Command triggers.

Threshold reference

Any threshold can be suffixed with -no-digest to exclude digest-only updates (e.g. major-no-digest, minor-only-no-digest). Updates with an unknown update kind (e.g. created-date-only changes) are passed through when threshold=all, but filtered out for all other threshold values.

Notes

• RESOLVENOTIFICATIONS is currently implemented for Gotify (auto-deletes the notification message after a successful update). Other providers can be extended to support it.
• Some messaging triggers (Slack, Telegram, Teams, Matrix, Mattermost, Rocket.Chat, Google Chat) also support DISABLETITLE (default false) to send only the body without a title line.
• You can set DD_NOTIFICATION_{trigger_type}_THRESHOLD to define a default threshold for all triggers of the same type, e.g. DD_NOTIFICATION_NTFY_THRESHOLD=minor (or DD_ACTION_{trigger_type}_THRESHOLD for action triggers).
• Triggers are executed by ascending ORDER; when two triggers have the same ORDER, they are sorted by trigger id.
• Triggers sharing the same trigger name (e.g. docker.update and discord.update) can share THRESHOLD; if exactly one threshold value is defined among them, that value is used for the others unless they override it explicitly.
• Setting ONCE=false with MODE=batch gives a report with all pending updates on every run.
• DIGESTCRON is validated with cron.validate() at registration time. An invalid cron expression causes a startup error with a descriptive message — the trigger will not be registered.
• MODE=digest accumulates update events in an in-memory buffer and flushes them as a single batch notification on the DIGESTCRON schedule. If the same container has multiple updates within the window, only the latest is included. Containers that are updated before the digest fires are automatically evicted from the buffer. Useful for daily email digests: DD_NOTIFICATION_SMTP_GMAIL_MODE=digest + DD_NOTIFICATION_SMTP_GMAIL_DIGESTCRON=0 8 * * *.
• MODE=batch+digest enables both modes simultaneously — immediate batch emails on each scan cycle plus a scheduled digest summary. Requires DIGESTCRON to be set.
• Note: Digest and batch modes still depend on the update-available notification rule being enabled (see below). If the trigger is excluded from update-available routing, no events reach the buffer.
• SECURITYMODE governs security-alert delivery independently of MODE. A trigger may legitimately want MODE=batch for update notifications and SECURITYMODE=digest for security findings. Digest and batch+digest modes buffer alerts per-scan-cycle (keyed by cycleId) and flush one summary per cycle on completion. Cycles with zero findings never emit. See the Security Hardening Guide for an end-to-end example.
• Scheduled scans do not emit security-alert events by default. Set DD_SECURITY_SCAN_NOTIFICATIONS=true to opt in. On-demand scans (UI button, POST /api/v1/containers/:id/scan, POST /api/v1/containers/scan-all) always emit.
• Notification deduplication (ONCE=true) is now persisted in the notifications_history store collection, so once=true dedup survives restarts. Previously the dedup state was lost on container restart, causing previously-suppressed notifications to re-fire.
• Digest and batch-retry buffers enforce a 5,000-entry cap and a 7-day retention limit. Entries exceeding the cap or age are evicted before the next digest flush.
• When release notes bodies are truncated to fit within the notification body limit, the truncated body is marked with a trailing … ellipsis so recipients know the notes continue at the source URL.

Notification Rules

Notification rules control which events fire which triggers. Each rule corresponds to an event type and has an enabled flag and an optional list of trigger IDs.

Dispatch behavior:

• update-available -- when its trigger list is empty, all notification triggers fire (legacy default). Once you assign specific triggers, only those fire.
• update-applied, update-failed, security-alert -- when their trigger list is empty, all notification triggers fire (same permissive default as update-available). Once you assign specific triggers, only those fire.
• agent-disconnect, agent-reconnect -- disabled by default. Enable them and assign triggers to receive disconnect/reconnect alerts. When their trigger list is empty, all notification triggers fire. These events always fire regardless of the threshold setting.

Rules are managed via GET /api/v1/notifications and PATCH /api/v1/notifications/:id (update enabled and/or triggers fields), or through the Notifications view in the UI.

Event Types

Beyond the classic update-available event, triggers can fire on additional events:

• update-applied -- fires after a container is successfully updated by a Docker or Docker Compose trigger. Useful for audit or confirmation notifications.
• update-failed -- fires when an update fails or is rolled back. Carries the container name and error message.
• security-alert -- fires when the Update Bouncer detects critical or high vulnerabilities during a pre-update scan. Includes a vulnerability summary.
• agent-disconnect -- fires when a remote agent loses its connection. This event skips threshold checks (always fires).
• agent-reconnect -- fires when a remote agent reconnects after losing connection. Only fires on true reconnects, not the initial startup connection. This event skips threshold checks (always fires).

Notification Outbox

Drydock uses a durable notification outbox to persist and retry failed notification deliveries. When a trigger call fails (network error, provider down, etc.), the delivery intent is saved and retried with exponential backoff and jitter rather than being silently dropped.

Default behavior:

• Max attempts: 5. After 5 failed attempts the entry moves to dead-letter status.
• Backoff: 30 s base, doubles per attempt, capped at 5 minutes. Up to 5 s jitter per retry.
• TTL: 30 days. Delivered and dead-letter entries older than 30 days are purged automatically.

API:

UI: The Notification Outbox page (Settings → Notification Outbox, route /notifications/outbox) shows tabs for Dead-letter, Pending, and Delivered entries with Retry and Discard actions.

Template Variable Reference

Template strings use ${expression} placeholders. Drydock provides two sets of variables depending on the trigger mode.

Simple mode variables

Legacy aliases (deprecated)

These aliases resolve to a single container property and will be removed in v1.6.0. Use the container.* equivalents instead.

Batch mode variables

Legacy alias (deprecated)

Expression syntax

Inside ${...} you can use:

• Property paths -- container.updateKind.kind
• Method calls -- local.substring(0, 15) (see allowed methods below)
• Ternary -- container.result.link ? container.result.link : "no link"
• Logical AND -- container.result && container.result.link
• String concatenation -- "Version: " + container.updateKind.remoteValue
• String and number literals -- "hello", 42

Allowed string methods: substring, slice, toLowerCase, toUpperCase, trim, trimStart, trimEnd, replace, split, indexOf, lastIndexOf, startsWith, endsWith, includes, charAt, padStart, padEnd, repeat, toString.

Examples

services:
  drydock:
    image: codeswhat/drydock
    ...
    environment:
      - DD_NOTIFICATION_SMTP_GMAIL_SIMPLETITLE=Container $${container.name} can be updated
      - DD_NOTIFICATION_SMTP_GMAIL_SIMPLEBODY=Container $${name} can be updated from $${local.substring(0, 15)} to $${remote.substring(0, 15)}

docker run \
  -e 'DD_NOTIFICATION_SMTP_GMAIL_SIMPLETITLE=Container ${container.name} can be updated' \
  -e 'DD_NOTIFICATION_SMTP_GMAIL_SIMPLEBODY=Container ${name} can be updated from ${local.substring(0, 15)} to ${remote.substring(0, 15)}'
  ...
  codeswhat/drydock