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

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¶