EDIT: Updated example YAML to match API for 1.0 release

Organizing GitHub notifications has always been annoying to me.

• Let’s face it - the notifications screen in GitHub itself is fairly lacking and you never click on it regularly, so using the GitHub UI is out.
• Consequently, most people flock to Gmail and its label system. This sucks because GitHub doesn’t allow you to subscribe to email on a per-project basis. Gmail filters are fairly powerful, and you can at least sort out the projects by the sender, the message body, etc. But even that is still lacking as Gmail won’t parse GitHub’s custom headers that they include in emails telling you why you are receiving the notification.
• Even if you do make Gmail filters work out for you, maintaining them in Gmail’s UI is painful, dumb experience.

Google Apps Scripts

A while ago I stumbled on a post by Lyzi Diamond about managing GitHub notification messages in Gmail with Google Apps scripts. The basic idea is that you can have a script written in Google Apps Script (Javascript, essentially) and set a cron-like timer for Google Apps to run it against your Gmail Inbox.

Thanks Lyzi! This solution works well for some people’s workflows. However, when I tried it there were a number of unforgivable drawbacks in my case:

• Google Apps Scripts are slow. Like, really slow. Looking at the logs for my script, it took ~4 seconds to add/remove a label. If you’re someone who wants to have lots of notifications sorted, this is simply too long as the script times out and notifications coming in start piling up unprocessed.
• As a result of the previous point, even if you manage to page through and get all the messages processed Google has a hard cap of 1 hour of scripting time, and gave me a lovely Service using too much computer time for one day. message within the first day of my use of it.
• It’s written in Javascript. ^_^

In summation, labeling large quantities of GitHub notifications with all of the previous methods had too many weird, annoying drawbacks and hacks that I’d never remember or want to maintain moving forward.

The Goal

• I want organized, labeled notifications for all of the projects that I’m interested in on GitHub.
• I want it broken down by organization and repository so I can see what’s going on where, and easily ignore what I want to at any time.
• I want notifications labeled according to my interaction with them: When I’m mentioned in a notification, when I’m assigned to something, when I’m generally participating…
• I want the management of these labels to be stupid easy. Setting a new one up should be as simple as adding a label in Gmail and adding that label to an organized configuration file, at most.
• I want notifications that don’t involve me directly to go straight to my archive, and notifications that do involve me to land right in my inbox with an unread notification popup.

[D]amn yo[u], [G]mail!

So I wrote a gem, and now I have all I want.

Labeling is controlled by a simple YAML:

And it needn’t even be this complex - this is just showing the flexibility of different features.

It’s called Dug, and it’s open source and available on GitHub.

Dug is meant to be stupid simple. It depends on a single, stupid easy Gmail filter that you’ll never have to change. It’s practically a gemified script with a configurable API, and as such you can programmatically configure and execute Dug’s runner class in any way you see fit (within a web app hook, a Rake task, a script, whatever). I personally use it as an installed gem with a config/yaml file and cron job. That’s it. It works marvelously. And it processes messages near instantly.

Let me know what you think! And contributions are always welcome. :)