Skip to content

Notification Providers

Jump to bottom
Farukk57 edited this page Apr 19, 2026 · 1 revision

Notification Providers

release-notifier supports two notification providers: ntfy and Home Assistant. You can use either or both simultaneously.

NOTIFY_PROVIDER=ntfy           # ntfy only (default)
NOTIFY_PROVIDER=homeassistant  # Home Assistant only
NOTIFY_PROVIDER=both           # both simultaneously

ntfy

ntfy is a simple HTTP-based push notification service. It's free, open source, and has apps for Android and iOS.

Setup

  1. Install the ntfy app:

  2. Subscribe to a topic, e.g. ntfy.sh/my-homelab-updates

  3. Configure release-notifier:

# .env
NTFY_URL=https://ntfy.sh/my-homelab-updates

Private topics

If your topic is protected with an access token:

NTFY_TOKEN=your_access_token

Self-hosted ntfy

NTFY_URL=https://ntfy.yourdomain.com/my-topic

Notification format

Notifications include:

  • Title — container name and version, e.g. Vaultwarden: 1.35.4 -> 1.35.5
  • Body — AI-generated summary with what's new, fixes, and action required
  • Priority — urgent for CVEs, high for breaking changes, default otherwise
  • Tags — emoji icons based on urgency
  • Action button — links directly to the GitHub release page

Home Assistant

Send rich push notifications via the Home Assistant mobile companion app. Also creates a persistent notification in the HA bell icon for a browsable history.

Setup

1. Install the HA companion app on your phone

2. Create a long-lived access token

Go to your HA profile → Security → Long-lived access tokens → create one called release-notifier.

3. Find your notify service name

Go to Developer tools → Actions → search notify.mobile_app. Your phone appears as something like notify.mobile_app_your_phone. Use the part after notify..

4. Configure

# .env
NOTIFY_PROVIDER=homeassistant   # or "both" to use ntfy too
HASS_URL=http://homeassistant.local:8123
HASS_TOKEN=your_long_lived_token
HASS_NOTIFY_SERVICE=mobile_app_your_phone

What you get

  • Mobile push notification — sent immediately to your phone
  • Persistent notification — appears in the HA bell icon (🔔), stays until dismissed, acts as a notification history
  • Urgency-based priority:
    • urgent (CVEs) → critical alert, bypasses Do Not Disturb on iOS
    • high (breaking changes) → high importance
    • default → standard notification

Critical alerts on iOS

For urgent notifications to bypass silent mode, enable Critical Alerts for the HA app:

Settings → Notifications → Home → Critical Alerts → On

Viewing notification history

Open Home Assistant → click the bell icon 🔔 in the top right. All release notifications are listed there with full summaries and release note links.

Using both providers

# .env
NOTIFY_PROVIDER=both
NTFY_URL=https://ntfy.sh/my-topic
HASS_URL=http://homeassistant.local:8123
HASS_TOKEN=your_token
HASS_NOTIFY_SERVICE=mobile_app_your_phone

Both notifications are sent for every new release. The ntfy notification goes to all devices subscribed to the topic, while the HA notification goes to the specific phone you configured.

Clone this wiki locally