Personal notifications
Bucker has two kinds of notification:
- Team alerts. Alert rules page a channel when telemetry crosses a line. They are configured under Alerts and are described in alert-rules.md. Nothing on this page changes them.
- Personal notifications. These are about things that happen to you: an approval you can decide, an issue assigned to you, an issue you follow regressing. You configure them under Settings › Notifications.
What reaches you, and how
Personal notifications use one short, closed list of event types. The inbox is built from the same list.
| Type | When | Inbox | Slack DM | |
|---|---|---|---|---|
approval_waiting |
An approval you can decide is waiting | on | on | on |
assigned |
Someone assigned an issue to you | on | on | on |
mention |
Someone mentioned you | on | on | on |
watched_regressed |
An issue you participate in regressed | on | on | off |
watched_resolved |
Someone else resolved an issue you participate in | on | off | off |
remediation_finished |
A remediation you started finished | on | off | off |
billing_usage |
Usage, spend and spike notices (owners and billing members) | — | on | — |
security_audit |
A security event your organization opted to alert owners on (owners only) | — | on | off |
deploy_shipped |
A release carrying commits you wrote was deployed | on | off | off |
alert_rule_broken |
An alert rule you own stopped working | on | on | off |
budget_breached |
A budget you own was breached | on | on | off |
shadow_report_ready |
A shadow-mode report you asked for is ready | on | off | off |
receipt_failed |
A receipt for an act you approved or ran failed | on | on | off |
fix_still_reported |
A fix you shipped is still being reported after its window | on | off | off |
window_ended |
A maintenance, freeze or grant window you opened ended | on | off | off |
digest |
Your daily or weekly digest | on | on | off |
The table shows the defaults. Each cell can be turned on or off.
GET /me/notifications
PUT /me/notifications { "changes": [{ "type": "assigned", "channel": "EMAIL", "enabled": false }] }
PUT /me/notifications { "approvalsBypassQuietHours": true }
These are account settings, not org settings. They apply in every organization you
belong to. billing_usage is the usage-notice switch that predates the matrix.
GET/PUT /me/notifications/usage still work, and they read and write the same cell.
A Slack DM can reach you only after you link your Slack account by running
/bucker link in Slack.
security_audit is opt-in per organization. An owner chooses which audit actions alert
(auditAlertActions on PATCH /orgs/:orgSlug/security-policy, from a closed list:
break-glass taken, support access changed, the security policy changed, the allowlist
cleared by an operator, a SCIM or org CI token created, SSO configured or removed, a
member's role changed, a custom role edited, an audit sink removed). The worker reads the
audit log after the fact, so an alert can never fail or slow the action it reports, and
the owner who caused an event is not told about it.
deploy_shipped comes from the release's commit list (the commits a release carries,
from its connected repository). A commit is yours when its author email is your account's
email, or when it is GitHub's private form (<id>+<login>@users.noreply.github.com) for
the GitHub account you connected under Connected sign-in accounts. You are told once
per deploy, however many of the commits are yours, and only by organizations you belong
to. A deploy reported more than a day after it happened is not announced.
The seven summary notices and their daily caps
The last seven rows above are summaries of things you own. They are capped per person, per organization and per UTC day, so a rule that flaps cannot fill the bell or your mailbox:
| Type | Cap per day |
|---|---|
alert_rule_broken |
10 |
budget_breached |
5 |
shadow_report_ready |
5 |
receipt_failed |
10 |
fix_still_reported |
5 |
window_ended |
10 |
digest |
1 |
Past the cap the notice is not lost. It is still recorded, but it is not shown in the inbox and no email or Slack DM is sent. The Summaries section says "N more today", and your next digest lists those notices. The other types (an approval waiting, an assignment, a mention) are never capped.
The digest as a notification
Each recipient gets one digest notification per digest: a row in the inbox's
Summaries section, a Slack DM if you turned that cell on (one message with the counts
per section and a link to your inbox), and the full email. The email is sent only when
the deployment has a real mail transport. Where mail is only logged (EMAIL_PROVIDER=console)
the email delivery is recorded as skipped with the reason no_mail_provider and is never
counted as sent. The digest has an approvals section: pending requests per action family,
the age of the oldest, and how many expire within a day. It carries counts only, never a
request id, plan or token.
The inbox
The bell in the dashboard header shows how many unread things are waiting on you in
the current organization. It opens your inbox. Open the inbox page goes to
/org/{org}/inbox, the same list on a full page. The inbox groups rows by what they
need from you:
| Section | Holds |
|---|---|
| Waiting on you | Approvals you can decide, while they are still undecided |
| Assigned to you | Issues assigned to you |
| Mentions | Comments that mention you |
| Issues you follow | Regressions and resolutions of issues you participate in |
| Finished | Fix runs you started that have finished, and deploys that shipped your commits |
| Summaries | The seven summary notices and your digest |
- Each row links to the issue or approval it is about. It never holds a copy of the conversation.
- Opening a row marks it read. Read state is stored on the server, so it follows you to other browsers and devices.
- An approval leaves Waiting on you as soon as anyone decides it.
- Summaries never counts on the bell. It is the last section, and shows "N more today" when notices went past their daily cap.
GET /me/inbox?orgSlug={org}
GET /me/inbox/count?orgSlug={org}
POST /me/inbox/read { "orgSlug": "{org}", "ids": ["…"] } or { "orgSlug": "{org}", "all": true }
The inbox is per person and per organization. Turning off a type's Inbox cell in the matrix keeps that type out of the inbox. Its email and DM still follow their own cells.
Issues you participate in
You participate in an issue if any of these is true:
- It is assigned to you. This is read live, so reassigning it moves the notifications too.
- You resolved it.
- You watch it. Use the Watch button on the issue page, or call
PUT /orgs/{org}/projects/{project}/issues/{issue}/watch { "watching": true }. - You commented on it. This one arrives with issue comments.
Unwatch stops all of these for that one issue, even when you are its assignee.
Participants get watched_regressed when the issue regresses, and watched_resolved
when someone else resolves it. The person who caused an event is never notified about
it. For example, someone who assigns an issue to themselves gets no "assigned to you".
Bucker builds these notifications from the records the product already keeps: the
issue's activity, fix runs and approval requests. They arrive however the change was
made, whether from the dashboard, Slack, the API, Jira or the ingest pipeline. Each one
is written once, even if a pass repeats. The sweep runs every minute in the worker. It
appears as personal-notifications in the operator console, where it can be paused.
The weekly digest
Under Settings › Notifications › Digest you can choose Weekly, on Mondays
(PUT /me/notifications { "digestCadence": "weekly" }). You then drop out of the
daily digest and get one email each Monday, per organization you own or administer. It
covers the previous seven days and uses the daily digest's format. Quiet hours delay it
on Monday the same way they delay the daily digest.
Quiet hours
You set one quiet window, under the digest settings (PUT /me/digest). It applies to
the digest and to every personal email and Slack DM:
- A notification that falls inside the window is held, not dropped. It is sent when the window ends.
- The inbox is never held.
- Approvals bypass quiet hours is the one exception, and it is off by default. When it is on, approval requests reach you at any hour.
- Team alert rules ignore personal quiet hours. A team decides who it pages.
Where this is defined
- The vocabulary and defaults:
code/domain/src/modules/notifications/vocabulary.ts. - The matrix and the delivery plan:
code/domain/src/modules/notifications/preferences.ts. - Participants and the watch:
code/domain/src/modules/notifications/participants.ts. - The sources, the fan-out and delivery:
sources.ts,fanout.tsanddelivery.tsin the same directory. The sweep's schedule iscode/workers/src/personal-notifications/. - The inbox:
code/domain/src/modules/notifications/inbox.ts; the bell and the list:code/frontend/src/components/shell/inbox-bell.tsx,code/frontend/src/components/inbox/. - The hooks for issue comments:
recordCommenterinparticipants.tsandnotifyMentioninfanout.ts.