A couple weeks ago, my colleague Bryan Housel posted an internal note at work about GitHub’s custom mail headers and how to use them to filter email notifications in Mail.app. Mapbox has a lot of GitHub repos, so we happily welcome any methods for managing what we call the “firehose.” But not all of us use Mail.app, so I took his workflow and figured out how to make it work in the Gmail web interface using Google Apps Scripts! Here’s how you can do that, too.
What is Google Apps Scripts?
What are these magical GitHub custom headers?
GitHub adds several custom headers to its email notifications. One of these,
X-GitHub-Reason, states the reason you are receiving the notification. Here is the full list of values for
X-GitHub-Reason from the GitHub API documentation:
subscribed— The notification arrived because you’re watching the repository
manual— The notification arrived because you’ve specifically decided to subscribe to the thread (via an Issue or Pull Request)
author— The notification arrived because you’ve created the thread
comment— The notification arrived because you’ve commented on the thread
mention— The notification arrived because you were specifically @mentioned in the content
team_mention— The notification arrived because you were on a team that was mentioned (like @org/team)
state_change— The notification arrived because you changed the thread state (like closing an Issue or merging a Pull Request)
assign— The notification arrived because you were assigned to the Issue
The reason for receiving a notification is a useful way to categorize messages when you’re receiving hundreds of them per day.
How can you make these work for you in Gmail?
Gmail provides lots of handy ways to manage your inbox. I use multiple inboxes to keep my messages visually separated based on how they’re labeled. Multiple inboxes are great because you can set multiple rules for what is to be included in each one – for example, I can have one inbox that only contains messages from my parents or my sister that are starred and have an “Urgent” label.
For my work email, my five inboxes are:
- Take Action — messages starred with a red bang.
- Assigned to me — messages labeled “Assigned to me”
- Participating — messages labeled “Participating”
- Mentioned — messages labeled “Mention by name” or “Team mention”
- Notifications — all GitHub notifications
The script I wrote runs through the new emails in my inbox and labels them appropriately so they show up in the correct inbox.
Okay, I’m sold! Show me the script!
Okay! Here it is!
What does this script do, exactly?
Glad you asked! This script:
- runs through the 50 most recent emails in your inbox
- adds a
GitHublabel if the message is from GitHub
- adds a
Notificationslabel if the message is from
- adds a
- adds a
Mention by namelabel if
- adds a
Team mentionlabel if
- adds an
Assigned to melabel if
- archives all messages labeled
- runs once per minute
Neat! How do I make it work with my Gmail account?
You only have to do a few things:
Add labels you want in Gmail
Add the following labels to your Gmail account:
- Mention by name
- Team mention
- Assigned to me
Any label you use in the script must already exist in your Gmail account. (Note: You can create labels programmatically in your script, but this script will run automatically over and over again, and you only want to create the labels once. Doing it manually is most efficient.)
Enable Google Apps Scripts for your account
Before you can write a script, you need to enable the Google Apps Scripts app in Google Drive. In your Google Drive home page, click New and hover over More. If you see Google Apps Script as one of the options, great! If not, click Connect more apps and connect the Google Apps Script app.
Start a new script
Click New and Google Apps Script to start a new script. You should see a page that looks like this:
Give the script a title and erase the empty
Copy and paste the script code into the body of your new script. Then run it!
Take the code I provided here and copy/paste it into the script. Make sure the drop down menu for starting function has
processInbox() selected, then click play to run it! Note: You may have to run the script several times at first if you have more than 50 GitHub notifications in your inbox.
Once it’s run a couple/few times, you can set a trigger for it to run once per minute by clicking the timer button.
Boom! You’re off to the races.
If you’d like to adapt this script to your specific needs, please do so! There are many methods available for interacting with Gmail using Google Apps Scripts. As always, please drop me a line if you have any questions!