Taming GitHub Notifications

•

The notification systems on GitHub aren’t all that good. In my experience, developers often miss things even when they really care about seeing them. In this post I want to share some strategies I used to tame the beast a little while ago. Obviously everyone prefers different workflows but perhaps it can serve as inspiration. GitHub continues to change things so I’m not sure how long this advice will hold up.

The first thing to know is that there are two completely independent notification systems: the notifications on the web interface and the email notifications. They work quite differently and I read somewhere that they are worked on by different teams. The first trick is to use email. It’s better for a few reasons.

  • The email includes the new message for you to read, whereas web just points you to the entire issue/PR and it’s up to you to figure out what’s changed.
  • You might get everything you need just by reading the email.
  • You can trivially mark a specific notification as “unread” or flag it if you want to follow it up later.
  • You can click on “View it on GitHub” in the footer to jump straight to that particular message if you need more context. (Most of the time*.)

However you don’t get updates about edits. You have to click through to the web version if you suspect something might have changed since the email was sent.

Until recently Gmail was collapsing “View it on GitHub” into a hidden footer which made the link difficult to access. Happily, somebody at GitHub or Google has tweaked something and now it’s readily visible. Since my work machine is a Mac I still use Mail.app out of habit.

The next problem is dealing with the sheer volume of emails, particularly working on a monorepo with a bunch of other people.

For a start, I set up GitHub to send notifications from work’s GitHub organisation to my work email address, leaving other activity to go to my personal email address. If you’re using a single GitHub account for both personal and work purposes you should probably already be doing this. In any case it’s the first layer of filtering.

Next, as a rule I don’t want any GitHub emails going into my work Inbox, which I reserve for humans and more refined varieties of spam. Therefore I use two tags which I called gh-all and gh-mentions, with rules to move GitHub emails into one of these folders. This loosely corresponds to “GitHub stuff I probably don’t care about” and “GitHub stuff I probably care about”. At time of writing about 20% of my notifications are going into the latter.

gh-all captures PRs, Issues and comments on them for repos that I’m watching but where I haven’t been directly tagged. In a mid-sized org there’s a fair bit of stuff going on that has nothing to do with me. I want to be able to skim it quickly but it’s probably not urgent. This is where those notifications go.

gh-mentions captures all issues/PRs that I’m subscribed to, generally because I’ve been tagged. If someone requests a review, mentions me by username, or if there is follow-up activity on an issue or PR I’ve posted on before, then I will get those notification emails here. I include CI failures from GitHub Actions here too. Most of this is interesting and may warrant a prompt response.

This lets me manage my GitHub email in a practical way. So long as I look at gh-mentions a couple of times a day then I’m confident I’m not blocking anyone, while maintaining a pretty good signal-to-noise ratio. gh-all I’ll skim through maybe once every couple of days just to see if there any new issues that are relevant to me.

These are the Gmail rules I’m using to send emails to these two tags. You might want to tweak them or make them more fine-grained. Two buckets is working well for me.

* GitHub remains fairly lacklustre about letting you jump to messages that are hiding behind “Show more…” links, or part of conversations that are marked Resolved. Fortunately this doesn’t matter often except in very large PRs, which are undesirable anyway.