---
title: Notifications
description: The Notifications switch, what raises an alert, the in-app list with its bell, and how desktop, web and iOS detect changes.
---

Pipedash alerts on failed pipelines, runs that take far longer than usual and provider outages. One Notifications switch controls the system notifications for all of them. The in-app list and its bell work without the switch.

Remote push and Live Activities are disabled in the current iOS release. The [Push relay](/docs/resources/push-relay) page covers the push server.

## The Notifications switch

The switch sits in Settings, under Notifications, and reads "Notifications". Its description reads "Get a system notification when a pipeline fails or runs longer than usual, and when a provider has an outage or recovers."

- **Default:** off on every platform.
- **Scope:** per device. The desktop app and each browser keep the setting in `localStorage` under the key `pipedash-notifications`. A second browser or device starts with the switch off.
- **Permission:** turning the switch on asks the system for permission. When the system refuses, the switch stays off and Pipedash shows "Notifications blocked" with a hint to allow notifications in the system or browser settings.
- **Older settings:** earlier versions had separate switches for failures and for outages. On desktop and web, either one on turns the new switch on.
- **Factory reset:** clears the setting.

On iOS the switch asks for more consent. The [background checks](#background-checks-on-ios) section covers it.

## What raises a notification

| Event | Title | Rule |
|---|---|---|
| New failure | `<pipeline> failed` | A refresh finds a pipeline that failed since the last refresh. A newer failed run on an already failed pipeline counts too. |
| Long-running run | `<pipeline> is running longer than usual` | A running pipeline passes 3 times the median duration of its recent successful runs. Each run raises one notification. |
| Provider outage | The incident, component or connection problem | A status page reports a partial or major outage, a controller check reports a major outage, or Pipedash cannot reach the provider. |
| Recovery | For example `GitHub is back to normal` | The outage ends. |

The body of a pipeline notification lists the repository and the provider name. The [Dashboard](/docs/features/dashboard) page describes the long-running status. The [Provider health](/docs/features/provider-health) page lists the outage rules, the cooldown of 15 minutes per issue and the recovery checks.

A pipeline that appears for the first time never raises a failure notification. Existing failures raise none when the app opens. A provider problem that exists at startup raises no outage notification either. Pipedash records these as the baseline and reports only later changes.

## In-app list and bell

The bell in the header opens the in-app notification list. The list does not need system permission and does not need the switch. It keeps the 50 latest items in memory and starts empty after a restart.

- **Bell dot:** the bell shows a dot while an item is unread. The dot is red for a failure, orange for a warning and green for a resolved issue. The most severe unread item sets the color.
- **Affecting pipelines now:** this section lists each provider with a current problem. A click opens the provider status view.
- **Recent:** this section lists the items. Each row shows the title, a label and the age. The label reads "Pipeline failed", "Running longer than usual", "Resolved" or the health level of the provider.
- **Actions:** the Mark all read button marks every item as read, and the Clear button empties the list. Closing the list marks all items as read.
- **Details:** a click on an item opens a dialog with the text and a link to the incident or status page. Pipeline items add an Open run history button. Provider items add a service status button.

An item with the same key replaces the older one. A new failure of the same pipeline replaces its earlier item.

## Detection on each platform

### Desktop app

The core emits a `pipelines-failed` event when a refresh finds a new failure, including a newer failed run on a pipeline that already failed. It emits a `provider-health-alert` event for each outage and each recovery. The interface adds both to the in-app list. With the switch on, it also sends a system notification.

### Web interface

The web interface has no `pipelines-failed` event. It compares each new pipeline list with the cached one. A pipeline counts as newly failed when its status is `failed` and either the previous status differed or the last run changed. The web server sends `provider-health-alert` events over the WebSocket.

After a WebSocket reconnect, the interface loads a fresh snapshot and compares it with the cache. A newly observed failure raises one notification. A recovery follows the latest snapshot. Pipedash cannot rebuild every event it missed while disconnected.

Browsers allow notifications only over HTTPS or on localhost. On other addresses the switch stays disabled and a note explains why. Detection runs in the open page, so a closed tab raises no notification.

### iOS

The iOS app raises local notifications on the device. It checks the system permission before every delivery, including after a change in the iOS Settings app. The app also checks in the background.

#### Background checks on iOS

Turning the switch on opens the dialog "Turn on notifications?" and then the iOS permission prompt. After consent, Pipedash copies the provider configurations and tokens, the proxy URL and the status page setting into a separate Keychain item. The item is readable after the user unlocks the device once following a restart, and only on this device.

- **Locked app:** the vault and the app lock stay locked. Background checks read only the Keychain copy.
- **Updates:** changes to providers or general settings while the app runs unlocked update the copy. Removing a provider drops its entry.
- **Removal:** turning the switch off or a factory reset deletes the copy. Revoking permission in iOS Settings only stops delivery.
- **Baseline:** Pipedash saves the current pipeline and provider state silently. Turning the switch on never reports failures or outages that already exist.

A `BGAppRefreshTask` asks iOS for a background run every 15 minutes. iOS decides when a run happens. It can skip a run in Low Power Mode or with Background App Refresh off. It never runs the task after a force quit until the app opens again.

Each run has about 23 seconds. The work happens in this order:

1. Status pages.
2. For each provider, the controller check and the pipeline refresh as separate jobs. A hanging pipeline request cannot hold back a controller result.
3. At most 25 checks for long-running runs across all providers. Later runs rotate through the rest.

A provider whose refresh could not start goes first in the next run. The background run reuses the provider setup, timeouts, quota pause and controller checks of the core. It never writes the pipeline cache.

The foreground and the background share one delivery record, so Pipedash notifies each failure, long-running run, outage or recovery once, whichever side sees it first. A return to the foreground cancels a running background check.