Notifications

Doco-CD can be configured to send notifications with Apprise to various services when a deployment is started, finished, or failed and on reconciliation events. You can find a list of all supported services and platforms in the Apprise documentation.

For that, specify the required settings in the app environment section and add an Apprise container to your docker-compose.yml file.

Settings¶

Example docker-compose.yml¶

Adjust your docker-compose.yml file to include the Apprise service and the necessary environment variables for the app:

services:
  app:
    container_name: doco-cd
    # add the code below to your existing docker-compose.yml file
    depends_on:
      apprise:
        condition: service_healthy
    environment:
      APPRISE_API_URL: http://apprise:8000/notify
      APPRISE_NOTIFY_LEVEL: success
      APPRISE_NOTIFY_URLS: "pover://{user_key}@{token},mailto://{user}:{password}@{domain}"

  apprise:
    image: caronc/apprise:latest
    restart: unless-stopped
    ports:
      - "8000:8000"
    environment:
      TZ: Europe/Berlin
      APPRISE_WORKER_COUNT: 1
    healthcheck:
      test: [ "CMD-SHELL", "curl -fsS http://localhost:8000/status >/dev/null || exit 1" ]
      interval: 30s
      timeout: 5s
      retries: 3
      start_period: 20s

Repeated failures¶

A failure repeats as often as its trigger. A poll job runs on its interval and a broken deployment fails the same way every run, so one fault produces one message per poll until somebody fixes it - an expired registry token can turn into hundreds of identical notifications overnight.

Failure notifications are therefore de-duplicated per stack:

• The first failure of a stack is sent immediately.
• While the failure stays the same, further notifications are skipped and repeated only once per APPRISE_NOTIFY_REPEAT_INTERVAL, so a long outage stays visible without flooding.
• A different error on the same stack is sent right away - it is new information.
• A successful notification for that stack (e.g. Deployment completed) clears the suppression, so it also acts as the recovery signal and the next failure is sent immediately.
• Set APPRISE_NOTIFY_REPEAT_INTERVAL to 0 to send every failure, unchanged or not.

Stacks are tracked separately per repository, target and Docker context, and the state is in memory: a restarted daemon sends the next failure again.

For the same reason a failed deployment notifies once, not twice. The stack reports its own failure, and the poll job or webhook that received the same error no longer repeats it under its own title. Logs and metrics are unchanged.

Metadata fields¶

When a notification is sent, the following metadata fields are included in the notification body:

Custom notification body¶

By default the notification body is the message followed by the metadata fields as key: value lines. Set APPRISE_NOTIFY_BODY_TEMPLATE (or APPRISE_NOTIFY_BODY_TEMPLATE_FILE) to a Go text/template to render the body yourself — useful to drop noisy fields, add a host label, or produce a one-liner when several stacks report into one channel.

The template is validated at startup: a syntax error or a reference to an unknown field stops doco-cd from starting. The title (emoji + optional [R] marker + title text) is not affected by the template.

{{ if ne .Level "success" }} — {{ .Message }}{{ end }}

The following fields are available:

{{ .DefaultBody }} renders the built-in body (message + metadata), so you can extend the default format instead of replacing it, e.g. {{ .DefaultBody }}\nhost: my-vm.

environment:
  APPRISE_NOTIFY_BODY_TEMPLATE: "{{.Emoji}} {{if .Target}}{{.Target}}/{{end}}{{.Stack}} — {{.Message}} ({{.Revision}})"

Commit changelog¶

.Commits is the list of commits that got deployed since the previously deployed commit, newest first. It is only populated on successful deploy notifications of Git sources; on the first deploy, on failures and for OCI sources it stays empty (a range over it just renders nothing). Each entry has:

Printing an entry directly ({{ . }}) gives shortHash subject.

environment:
  APPRISE_NOTIFY_BODY_TEMPLATE: |
    {{ .DefaultBody }}
    {{ range .Commits }}- {{ .ShortHash }} {{ .Subject }} ({{ .Author }})
    {{ end }}

Up to 50 commits are listed. After a rebase or force-push the list starts from the point where the histories diverged.

The changelog is best-effort: with a small GIT_CLONE_DEPTH the previously deployed commit may sit beyond the shallow boundary, in which case the list is truncated or omitted. It never blocks the notification.

Reconciliation notifications¶

If a notification was triggered by reconciliation, the title gets a short [R] marker.

Reconciliation notifications also include a reconciliation: block in the body metadata.

Metadata fields¶