# Alerts

**Alerts** is where incidents are worked and where you choose what reaches you. ShipVitals has sensible rules on from the start, so you get alerts without setting anything up.

What you can do depends on your role:

- **Owner** and **Admin**: everything, including rules for all projects and **Workspace channels**.
- **Editor**: works the incidents of their projects, and edits those projects' rules.
- **Viewer**: reads incidents and rules, and mutes a rule for themselves.
- Everyone has their own channels, routing, quiet hours and digest on **Delivery**.

Without amounts, the **Budget**, **Spend anomaly** and **MRR drop** rules aren't shown. **Connection failure** is for owners and admins.

## Open it

In the sidebar, choose **Alerts** (on a phone, **Alerts** in the bar at the bottom), or press `g` then `a`. The number beside it counts open incidents; on the narrow sidebar and on a phone it is a small badge on the icon. The bell's badge is a different count, your unread notices, and a notice about an incident is read once you have that incident open, however you got to it. The page has **Open**, **Resolved**, **Rules** and **Delivery**. **Open incidents** in the command palette (`⌘K` / `Ctrl K`) comes here too, and so does the bell.

## Work an incident

**Open** lists what's happening, the worst first, each with its project, **Critical**, **Warning** or **Info**, and how long it's been open ("open 15 min"), or "Acknowledged by Ana", "Snoozed until 14:00" or **Flapping**. "3 checks" says when several failures were folded into one. With nothing open: "No open incidents."

On a computer the first incident shows beside the list. `j` `k` move between them. On a phone, press one to open it, and **Back to incidents** to go back.

An incident shows **What happened** and its timeline. Once it has been routed to a channel, **Where it went** follows: each channel and "Delivered …", "Waiting to send", "Failed …", "Held for quiet hours" or "Folded into a later message". A chart shows the figure around that moment.

- **Acknowledge** (`a`): you have it. The page says "Acknowledged. Reminders have stopped for everyone."
- **Snooze** (`s`): "Snooze for how long?" Choose **1 hour**, **Until tomorrow 09:00** or **1 week**. `Esc` closes the question.
- **Mute this rule for this project** (`m`): "You won't be alerted about this rule here." with **Undo** for 10 seconds. An incident with no project says **Mute this alert**: it covers that one problem, "You won't be alerted about this again."
- **Mute for everyone**: for those who manage alerts. "No one will be alerted about this rule here."
- **Open**: the tab where the figures live.

Acknowledge, Snooze and **Mute for everyone** are for owners, admins and the project's editors. A viewer has **Mute this rule for this project** and **Open**. **Unmute this rule** (or **Unmute this alert**) undoes a mute later, and so does **Muted rules** on [Delivery](#muted-rules).

Incidents recover on their own when the check passes again. They move to **Resolved**, which lists the last 90 days: "Recovered after 14 min".

### A public note

For a project's incident, those who can publish its status page have **Public note** ("Shown with this incident on your status page, for anyone to read.").

1. Type the note.
2. Press **Save note**. The page says "Your public note is saved."

Empty the field and save to remove it. See [The status page and badge](status-page-and-badge.md).

### What changed since you last looked

The Portfolio's "Since …" line opens **Open** with "What changed since …". Press **Show everything open** to see all of them.

## Rules

**Rules** lists what raises an alert, each as a sentence, with **On** or **Off**, its severity and where it comes from (**Default**, **Edited for the workspace**, **Edited for this project**):

**Check failure**, **TLS certificate expiry**, **Expiry ladder**, **Connection failure**, **Failing tests on main**, **Budget**, **Spend anomaly**, **Free-tier exhaustion**, **MRR drop** (off until you turn it on), **Runner offline**, **Release not shippable** and **Critical CVE**.

The last three are about the machines that run your checks ([Pair a runner](pair-a-runner.md)) and the [release gate](release-gate.md):

- **Runner offline**: "Alert when an always-on runner is offline for 30 minutes, and raise it after 4 hours. A laptop that sleeps never alerts." It's a warning, and critical after the hours. The minutes can't go below 10.
- **Release not shippable**: "Alert when {project} goes from Shippable to Not yet, and raise it if it's still not shippable after 3 days." Proof running out (Unproven) raises nothing. It resolves when the project is Shippable again.
- **Critical CVE**: "Alert when a scan on {project} finds a critical CVE." It's critical, and more critical CVEs alert again. Whether one stops a release is the gate's own setting.

To change one:

1. Under **Rules for**, leave **All projects** or choose a project. "A rule edited here applies to this project only."
2. Press **Edit** on the rule.
3. Change the numbers in the sentence, and the severities under it. **Alert on this rule** turns it on or off.
4. Read the preview: "Would have fired 3 times in the last 30 days: …" or "Wouldn't have fired in the last 30 days."
5. Press **Save rule**. The page says "Rule saved."

**Reset to default** puts back what it was: "Rule reset." **Cancel** leaves it alone.

**Connection failure** applies to the whole workspace, so a project can't have its own. Editors see **Edit** once they've chosen a project of theirs.

## Delivery

**Delivery** is yours: your channels, where each severity goes, your quiet hours, your mutes, your digest and your calendar link.

### Your channels

**Your channels** lists where alerts reach you. Email is always on. Each channel shows its last result ("Delivered …", "Nothing sent yet", or "Failed …" with what to do) and **Send test**. The page says "Test sent to …. Its result appears here in a moment." A channel can take five tests an hour.

A channel that keeps failing says "Turned off after repeated failures". Press **Remove** on one to take it off: "ShipVitals stops sending there at once. Add it again to go back."

**Slack**

1. Press **Add to Slack**.
2. Choose the channel on Slack's page, and allow it.
3. Back on Delivery, the page says "Slack is connected. Send a test to check it."

**Discord**

1. In Discord: **Channel settings → Integrations → Webhooks → Copy URL**.
2. Press **Add Discord**, paste the **Webhook URL** and press **Add**.

**Telegram**

1. Press **Open Telegram**. **Connect Telegram** opens: "Open the ShipVitals bot and press Start. No phone number is shared with ShipVitals."
2. Press **Open Telegram** in it, then **Start** in Telegram. The dialog says "Waiting for Start…".
3. It closes by itself, and the page says "Telegram is linked."

**A webhook**

1. Press **Add a webhook**. "ShipVitals sends a signed JSON POST for each alert, and retries for 24 hours."
2. Paste the **Webhook URL**, give it a **Name** if you like, and press **Add**.
3. **Your signing secret** opens. "This is the only time it's shown. Keep it with your receiver." Press **Copy your signing secret**.
4. **Verify a delivery** has a snippet for your receiver, with **Copy the verification snippet**. It checks the `ShipVitals-Signature` header.
5. Press **Done**.

Closing it with `Esc` asks first, because the secret won't show again: **Close anyway** or **Keep it open**.

**Browser push**

1. Press **Turn on browser push**, in the browser that should get them.
2. Allow notifications when the browser asks. The page says "Browser push is on for this browser."

Each browser is listed under the channel ("This browser · added Nov 5") with **Remove**.

**Desktop app**

Added for you when you sign in the [desktop app](install-the-desktop-app.md) on a computer. Alerts show there as notifications, on every computer signed in to the app, and never with amounts: "Alerts show on each computer signed in to the app, never with amounts. Sign one out in Account → Devices." Each computer is listed under the channel. To stop one getting them, sign it out in **Account settings → Devices**; there's no **Remove** beside it here. With none signed in: "No computer is signed in to the app. Alerts reach it again once you sign in."

Buttons for channels ShipVitals isn't set up to use don't show.

### Workspace channels

Owners and admins. **Workspace channels** adds a Slack channel or webhook for everyone: **Add to Slack** and **Add a webhook**, as above. Each one has **Critical**, **Warning** and **Info** boxes for what it receives.

### Routing

**Routing** is a table of severities and your channels. Tick a box to send that severity there. It saves at once: "Routing saved."

A severity with no box ticked says **Digest only**.

### Quiet hours

1. Tick **Hold alerts during quiet hours**.
2. Set **From** and **To**, in your own time zone.
3. Leave **Let critical alerts through** ticked, or untick it.
4. Press **Save quiet hours**. The page says "Quiet hours saved."

What's held arrives in your next digest.

### Muted rules

**Muted rules** lists your mutes and those for everyone. Single alerts muted on no project show together, with how many: "Expiry ladder · 3 alerts". Press **Unmute** to lift the row, all of them: "… alerts again." With none: "Nothing is muted."

### Digest and calendar

See [The morning digest](digest.md) and [Subscribe in your calendar](expiries-and-calendar.md#subscribe-in-your-calendar).

On a phone these sections stack, and **Routing** scrolls sideways.

## Keyboard

| Key | Does |
|---|---|
| `j` `k` | Move between incidents |
| `a` | Acknowledge |
| `s` | Snooze |
| `m` | Mute the rule for this project |
| `Esc` | Close the snooze question |

Single keys follow **Single-key shortcuts** in [Account settings](account-settings.md).

## When it doesn't work

| The page says | What to do |
|---|---|
| "That didn't work. Try again in a moment." | Nothing changed. Try again. |
| "This didn't load." | Press **Try again**. |
| "This incident isn't there any more, or you don't have access to it." | Choose another incident. |
| "This incident has already resolved." | Nothing to do. |
| "This incident isn't about a project, so it can't appear on a status page." | A public note needs a project's incident. |
| "That address can't be used. Check it and paste it again." | Check the **Webhook URL**. |
| "This channel has had five test messages this hour. Try again at …" | Wait until then. |
| "This channel isn't set up on ShipVitals yet." | Use another channel. |
| "Your browser refused notifications. Allow them for this site in its settings, then try again." | Allow them, then press **Turn on browser push** again. |
| "This browser can't show push notifications." | Use another browser. |
| "This link has expired. Close this and open Telegram again." | Press **Close**, then **Open Telegram**. |
| "Slack didn't connect. Try Add to Slack again." | Press **Add to Slack**. |
| "Check the numbers in the sentence." | Change the rule's numbers. |
| "Changing this amount takes access to the project's financials." | Ask an admin to change it. |
| "One of these channels is gone. Reload and try again." | Reload the page. |
