Getting Started with GitHub: Part 2 -- Best practices for notifications

GitHub is most powerful when you use it to collaborate with others. We’ll send you notifications to make this collaboration easier, keeping you updated on activities and conversations that involve or interest you.

Here are some tips for making your notifications as helpful as possible.

Understanding notifications

Understanding the available types and delivery methods of notifications can help you optimize your notifications preferences.

Types of notifications

There are two main types of notifications: participating and watching.

Participating notifications are for events that directly involve you. We’ll send these notifications if you or a team you’re in has been mentioned in a comment, assigned to an issue, or requested to review a pull request, for example.

If you’d like to be updated about events that don’t directly involve you, you can watch a repository or team discussion. You’ll receive watching notifications for every issue, pull request, and release created in these repositories and every post in these team discussions. You can check which repositories you’re watching here.

These are just a few examples of participating and watching notifications we’ll send. See the full list.

Delivery methods

You can choose to receive both participating and watching notifications on, via email, or both.

These notifications have a shared read state. If you enable both web and email notifications, opening an email notification will mark the web notification as read. If this shared read state doesn’t work for you, learn how to prevent your web notifications from being marked as read.

Getting started with notifications

Now that you understand how notifications work, it’s time to choose your preferences.

First, follow this guide to choose your delivery methods—if any!—for participating and watching notifications.

If you enable email notifications, you’ll have a few more choices to make. Scroll down to Email notification preferences.

Choose a default notifications email address. Note that your default notifications email address is not the same as your primary email address, which receives GitHub system messages (such as repository transfer notifications).

Then, choose whether you want to receive notifications for each of the following events:

* Comments on issues and pull requests
* Pull request reviews
* Pull request pushes

Finally, decide whether you want to receive notifications for your own actions. This can be helpful if you’d like your email inbox to include the full history of an issue or pull request, including your own comments.

Notifications level: expert

Now that you’ve chosen your basic preferences, you can make notifications even more powerful by taking advantage of these additional features:

Disable automatic watching

You may be automatically receiving notifications for all repositories you have push access to. If you have access to a large number of repositories, this might be too noisy. Follow this guide to disable automatic watching.

Custom routing

If you’re a member of any organizations, you can receive notifications at different verified email addresses depending on the organization that owns the repository. Learn how to enable this custom routing.

Note : This feature is only available for organization members. If you don’t see a custom routing option in your settings, you might be an outside collaboratorinstead.

Email service hooks

You can get email or web notifications when new commits are pushed to a pull request you’re subscribed to. If you’d like to be notified of every push to a repository, you can set up an email service hook.


Each email notification includes headers that provide information about the notification and why you’re receiving it. Learn how to see email headers in Gmail.

You can use these headers to set up Gmail filters based on the repository the notification is about or the reason you’re receiving the notification. Here’s an example:

Matches: from:( to:(
Do this: Skip Inbox, Apply label "Notifications"

	Matches: from:( to:(
Do this: Skip Inbox, Apply label "Notifications/Mentioned"

	Matches: from:( to:(
Do this: Skip Inbox, Apply label "Notifications/Team"

	Matches: from:( to:(
Do this: Skip Inbox, Apply label "Notifications/Author"

With these filters, all email notifications from GitHub will skip your inbox. Labels will also be applied to each email that indicate why you received the notification: you were mentioned, a team you’re a member of was mentioned, or you created the issue or pull request.

Note : Sometimes you will be subscribed to an issue or pull request for one reason (for example, you commented on an issue) and that reason will later change (for example, you are directly mentioned in a later comment on that same issue). This will change the notification reason if the new reason is considered more important than the original reason. For eample, mention overrides comment, so the cc address for email notifications about that issue will be going forward.

Other headers can help you troubleshoot when you receive notification emails you weren’t expecting. Usually, this happens when a different email address is set up to forward notifications to you. You can check the X-GitHub-Recipient and X-GitHub-Recipient-Address headers to see which account the notification was intended for.

See the full list of email headers for email notifications.


If you want the granular control of filtering but prefer web notifications, consider using Octobox. It’s an open-source project that adds filters and an extra “archived” state to web notifications:

Octobox adds an extra “archived” state to each notification so you can mark it as “done”. If new activity happens on the thread/issue/pr, the next time you sync the app the relevant item will be unarchived and moved back into your inbox.

Quite a few members of the Support Team use it, including me!

Need help?

We want notifications to make collaboration on GitHub easier for you. If you’re having any trouble with your notifications, let the Support Team know. We’ll be happy to help!