Notifications

Diffinery tells you about activity in two places: the notifications list in the web UI, and email. Both follow GitHub's rules: you hear about issues and pull requests you take part in, everything in repositories you watch, and workflow runs you started. This page explains what you get, how to change it, and every email Diffinery can send.

#The notifications list and notification settings

Two pages share the name, and they do different things:

The list only shows what your settings let through. To get fewer (or more) entries in the list, change the On Diffinery column in the settings; to change your email, change the Email column.

#The notifications list

The bell in the header opens Notifications (/notifications). It has two views, Unread and All, and shows your 100 most recent notifications. Each entry has an icon for its kind (a pull request, an issue, a comment, a failed run in red, an organization, a repository or an invitation), a title such as diffy commented on acme/website#42: Cache build artifacts, its kind (for example issue comment, pull request review or run failed) and when it happened.

• Click an entry to open what it is about; that marks it read.
• Click the check mark (Mark as read) next to an unread entry to mark only that one read.
• Click Mark all as read to clear the list.
• Click the gear button (Notification settings) to open Settings → Notifications.

Your dashboard also shows up to 8 unread notifications under Unread notifications.

You get an in-app notification for:

• issue and pull request activity you take part in, when Participating → On Diffinery is on,
• activity in repositories you watch with All activity, when Watching → On Diffinery is on,
• failed workflow runs you started, when Actions → On Diffinery is on,
• a run waiting for your approval to deploy to an environment where you are a required reviewer ("Deployment to production in acme/website is waiting for your review"), when Actions → On Diffinery is on,
• someone inviting you by username to an organization or a repository (kind invitation, for example "<admin> invited you to acme as member"); it opens Settings → Invitations (see Invitations you receive),
• someone giving you a repository role at once, without an invitation, because you are a member of the organization that owns the repository or already a collaborator on it (kind repo access, for example "<admin> gave you write access to acme/website"). This comes from Add people, the role menu on Settings → Collaborators or the API.

The last two are always sent, whatever your settings. The invitation email belongs to the Account group, which can't be turned off; the access email belongs to the Repositories group.

Your own actions never create a notification for you. Other repository and organization events (organization role changes, removals, repositories created or deleted), and security and account events, are sent by email only.

#Email groups

Every email belongs to one group. Security and account emails always send; you can turn the others off.

#Notification settings

Open Settings → Notifications (/settings/notifications). The top of the page shows the address emails go to (your account's email address) and the address they come from (notifications@diffinery.com).

The Notify me about table has a row per group with an On Diffinery checkbox (the notifications list) and an Email checkbox:

Below the table:

• Email me about my own comments and changes (off by default). When on, you also get emails about comments, reviews and changes you made yourself, like GitHub's "Include your own updates".
• Watch repositories I create (All activity) (on by default). New repositories you create, in the web UI or through the API, are watched with All activity.

Under Morning digest:

• Email me a morning digest (off by default).
• Hour and Time zone: when it goes out, in your time zone. Until you save one, the time zone is your browser's.
• On Saturdays and Sundays too (off by default).

When the digest is on, the page says when the next one goes out. See The morning digest.

Click Save notification settings. You see "Notification settings saved."

The same page lists Watched repositories (every repository you watch or ignore, with a menu to change the level) and Recent emails to you (the last 20, with their status), and has Send me a test email and Send me my digest now buttons.

#Who gets notified about issues and pull requests

For each event on an issue or pull request, Diffinery works out who is taking part:

When several apply, the email gives the first one in this order. Mentions use @username outside code blocks and inline code.

What sends:

Rules that apply to every event:

• Your own actions don't notify you, unless you turn on Email me about my own comments and changes (email only; such emails carry the reason your_activity).
• A repository set to Ignore sends you nothing about its issues, pull requests and workflow runs.
• A muted thread (you clicked Unsubscribe) sends you nothing, except when that event @mentions you, assigns you or asks for your review.
• You must still be able to read the repository. People who lost access stop hearing about it.
• Agents don't receive email.

#Watch a repository

The Watch menu at the top of every repository sets how much you hear about it:

Choosing a level saves it right away ("Watching acme/website: All activity."). You can also change levels from the Watched repositories list in Settings → Notifications.

With the API (GitHub's repository subscription endpoints):

# Watch all activity
curl -X PUT https://diffinery.com/api/v3/repos/acme/website/subscription \
  -H "Authorization: Bearer dfy_..." -H "Content-Type: application/json" \
  -d '{"subscribed": true}'

# Ignore the repository
curl -X PUT https://diffinery.com/api/v3/repos/acme/website/subscription \
  -H "Authorization: Bearer dfy_..." -H "Content-Type: application/json" \
  -d '{"ignored": true}'

# Back to participating only
curl -X DELETE https://diffinery.com/api/v3/repos/acme/website/subscription \
  -H "Authorization: Bearer dfy_..."

Watching, ignoring and subscribing to issues also work on archived repositories, which otherwise refuse every change.

GET /api/v3/repos/{owner}/{repo}/subscription returns {"subscribed": true|false, "ignored": true|false, ...}, or 404 not subscribed when you are on the default participating level (as GitHub does). PUT with {"subscribed": false} also returns you to participating. Changing the level needs a write or admin token.

#Subscribe to or mute an issue or pull request

The sidebar of every issue and pull request has a Notifications section with one button:

• Subscribe follows the thread even if you aren't taking part: "Subscribed. You'll be notified about all activity."
• Unsubscribe mutes it: "Unsubscribed. You'll still be notified if you're @mentioned, assigned or asked to review."

The text under the button says why you are or aren't receiving notifications, for example "You're receiving notifications because you commented." or "You muted this pull request."

#Workflow run notifications

When a workflow run finishes:

Failed and timed-out runs send an email and an in-app notification. Successful runs send an email only to people who turned off Only failed runs. Cancelled runs send nothing. The email lists every job with its result and the first failure message, and links to the run. Set a repository to Ignore to hear nothing about its runs, for example a test repository whose CI you expect to fail.

#Unsubscribe links

Every email in a group you can turn off has unsubscribe links in its footer, and List-Unsubscribe and List-Unsubscribe-Post: List-Unsubscribe=One-Click headers (RFC 8058), so mail apps show their own Unsubscribe button.

The mail app's one-click button (List-Unsubscribe) turns off email for the group the email belongs to, the same as Unsubscribe from emails like this: for an issue or pull request email, that's every Participating email (or every Watching one, when you got it because you watch the repository). To mute just one thread, use Mute this thread in the footer instead. You can turn the group back on in notification settings.

The links are signed, so they work without signing in and can't be altered to change someone else's settings. Each link works for a year after the email was sent (links from before links carried an expiry work until October 16, 2027); after that, change what you get in notification settings. Opening one shows a page naming the change (for example "Mute acme/website#42") and the account's username, though not its email address, with a button to confirm; after confirming you can click Undo. Security and account emails have no unsubscribe links.

#Email headers

Every email has an HTML and a plain-text version and these headers, which you can use in mail filters:

#X-Diffinery-Reason values

#When Diffinery stops emailing you

When email to your address bounces for good (the mailbox doesn't exist or the server refuses it), or you mark an email from Diffinery as spam, Diffinery puts your address on its suppression list and sends nothing to it any more: no notifications, and no security alerts, sign-in links or account recovery emails either. A site administrator can also suppress an address by hand.

Settings → Email (/settings/email) shows whether your address is suppressed, since when and why, and the notifications settings page shows a warning too. To get email again after a bounce or a spam report:

1. Make sure the inbox works (and, after a spam report, that you want Diffinery's email).
2. On Settings → Email, click Send a verification email. It is the one email that goes to a suppressed address, and you can ask for 3 an hour.
3. Open the link in it within 24 hours, signed in to the same account, and click Confirm and get email again.

If a site administrator suppressed your address, only an administrator can lift it. If the verification email itself fails with E_RECIPIENT_SUPPRESSED, Cloudflare's own list still holds the address: ask a site administrator.

With the API: GET /api/v3/diffinery/email returns your address and suppressed (null, or reason, detail, created_at and owner_can_lift), and POST /api/v3/diffinery/email/verification sends the verification email.

#Every email Diffinery sends

The Kind column is the X-Diffinery-Kind header. Site administrators can preview every one of these under Settings → Email (see Site administration).

Issue and pull request emails (thread) come in these variants:

#Send a test email

Click Send me a test email on Settings → Notifications. Diffinery sends it right away (not through the queue) and shows "Test email sent to <address>." or the reason it wasn't sent, for example "The test email was skipped: ...".

You can send at most 5 test emails an hour; more answer 429 you can send at most 5 test emails an hour; try again later.

With the API (needs a write or admin token that isn't limited to repositories):

curl -X POST https://diffinery.com/api/v3/diffinery/emails/test -H "Authorization: Bearer dfy_..."

{ "status": "sent", "messageId": "..." }

status is sent, skipped or failed, with a detail when it wasn't sent.

#Notifications API

The settings object, with its defaults:

{
  "participating": { "web": true, "email": true },
  "watching": { "web": true, "email": true },
  "actions": { "web": true, "email": true, "failuresOnly": true },
  "repos": { "email": true },
  "orgs": { "email": true },
  "ownActivity": false,
  "autoWatch": true,
  "digest": { "email": false, "hour": 8, "timeZone": "UTC", "weekends": false }
}

digest.hour is 0 to 23 and digest.timeZone an IANA time zone, such as Europe/Istanbul; anything else returns 422. To get the digest at 7:00 in Istanbul:

curl -X PUT https://diffinery.com/api/v3/diffinery/notification-settings \
  -H "Authorization: Bearer dfy_..." -H "Content-Type: application/json" \
  -d '{"digest": {"email": true, "hour": 7, "timeZone": "Europe/Istanbul"}}'

For example, to stop watching emails and get every workflow run result:

curl -X PUT https://diffinery.com/api/v3/diffinery/notification-settings \
  -H "Authorization: Bearer dfy_..." -H "Content-Type: application/json" \
  -d '{"watching": {"email": false}, "actions": {"failuresOnly": false}}'

The response is the full settings object. An unknown key returns 422 unknown setting <key>. Only people have notification settings; agent tokens get 403 only people have notification settings.

#Delivery

Emails are queued and sent through Cloudflare Email Sending from notifications@diffinery.com. A failed send is retried with increasing delays. Every email Diffinery tries to send is logged for 90 days with its status, which you can see under Recent emails to you or with GET /api/v3/diffinery/emails. A skipped email has a reason:

#How notifications differ from GitHub

• The participating, watching and ignore rules, @mention handling, thread subscriptions, X-Diffinery-Reason (for X-GitHub-Reason) and the /repos/{owner}/{repo}/subscription API follow GitHub.
• Diffinery has no custom watch level (such as releases or discussions only).
• Settings are per group, for the notifications list and email separately. There are no per-organization email routes; every email goes to your account's address.
• Security and account emails can't be turned off.
• The notifications list shows your 100 most recent notifications and has no per-thread done or saved states.
• Being added to an organization or a repository with Add people always creates an in-app notification, with no setting to turn it off.