Email Notifications

UniTrack can email project members when something needs attention — starting with quality-gate failures. Notifications are off by default and send nothing until an SMTP server is configured.

1. Enabling

Two things are required:

  1. An SMTP server, via the standard Spring spring.mail.* properties.

  2. unitrack.notifications.enabled=true.

spring:
  mail:
    host: smtp.example.com
    port: 587
    username: ${MAIL_USER}
    password: ${MAIL_PASSWORD}
    properties:
      mail.smtp.auth: true
      mail.smtp.starttls.enable: true

unitrack:
  notifications:
    enabled: true
    from-address: [email protected]
    base-url: https://unitrack.example      # used for links in emails

If spring.mail.host is unset, no mail sender is created and notifications stay disabled — the app starts and runs normally regardless. Sending is best-effort: a failure to deliver is logged and never affects ingest.

2. Quality-gate failure

When a run is ingested and its quality gate fails on the watched branch (the project’s base branch, default main), UniTrack emails the project’s members.

Aspect Behaviour

Trigger

Gate result is FAILED on a run whose branch equals the project’s base branch.

Recipients

Project members who have an email address on file. No members with an address → no email.

Content

Project, run number, branch/commit, pass/fail totals, the failing gate rules, and a link to the run.

Failures on feature branches do not notify — only the watched branch does, to keep noise down.

3. Token-expiry reminder

A daily scheduled job emails the owner of any personal API token that is within 7 days of expiring, so it can be rotated before CI starts failing on a dead token. Each token is reminded at most once. Tokens with no expiry, or whose owner has no email, are skipped. The schedule defaults to 08:00 daily and is overridable:

unitrack:
  notifications:
    token-expiry-cron: "0 0 8 * * *"   # Spring cron expression

4. Per-user preferences

Each user controls which emails they receive from their profile page — two toggles, both on by default:

  • Email me on quality-gate failures

  • Email me before my API tokens expire

Opting out suppresses that notification type for that user (other recipients are unaffected). A token whose owner has opted out is still marked as reminded, so it is not re-checked daily.

5. Settings

Property Meaning

unitrack.notifications.enabled

Master switch (default false).

unitrack.notifications.from-address

From address for outgoing mail.

unitrack.notifications.base-url

Base URL for absolute links in emails.

unitrack.notifications.token-expiry-cron

Cron for the token-expiry reminder job (default 08:00 daily).

spring.mail.*

Standard Spring Boot SMTP configuration.