Cover image for Customized GitHub Notifications for MacOS
Doctolib Engineering

Customized GitHub Notifications for MacOS

darrenberg profile image darrenberg ・2 min read

GitHub has two choices for notifications: email or a small blue dot in the corner of the page. As a developer at Doctolib I get lots of notifications throughout the day, which means either frequent email alerts or keeping a close eye on the blue dot.

I wanted something in the middle, so I wrote a script to generate desktop notifications at a frequency I can choose.

Alt Text

Here’s the repository if you want to skip ahead to the code: https://github.com/darrenberg/github-notifications

Notification Content

The GitHub API has everything we need and we can parse the output with a command-line utility called jq.

Alt Text

Alt Text

Authentication and Password Storage

The easiest way to connect to the GitHub API is by creating a personal access token, which can be scoped to only access notifications.

Alt Text

However, storing this token in my script wouldn’t be very secure, so I used the MacOS Keychain.

Remember to generate a new personal access token if you accidentally post it on DEV

It’s easy to add an entry from Keychain Access and you can retrieve it from the command line with find-generic-password. For more information, check out https://www.netmeister.org/blog/keychain-passwords.html

Desktop Notifications

I used terminal-notifier to create the desktop notification. You can control whether it’s a banner or alert in the MacOS Notification Preferences.

echo "Piped Message Data!" | terminal-notifier -sound default

Alt Text

The Script!


USER=$(git config user.email)
TOKEN=$(security find-generic-password -a github_token -w)

while true
  curl -s -u $USER:$TOKEN  https://api.github.com/notifications \
    | jq -r '.[] | select(.unread) | [.subject.type, .reason, .subject.title] | @sh \
    | xargs -n 3 sh -c \
    'terminal-notifier -title "GitHub Notification" -subtitle "$0 $1" -message "$2" -open “https://github.com/notifications"'
  sleep $(($1 * 60))

Simply pass the number of minutes to wait between calls (e.g. ./notify.sh 10 will run every 10 minutes) and it will show you all your unread notifications with a link to GitHub. Or take out the infinite loop and run it as a cron job.

Alt Text

Detailed installation instructions can be found at https://github.com/darrenberg/github-notifications


According to Larry Wall, the original author of the Perl programming language, there are three great virtues of a programmer; Laziness, Impatience and Hubris:

Laziness: The quality that makes you go to great effort to reduce overall energy expenditure. It makes you write labor-saving programs that other people will find useful and document what you wrote so you don’t have to answer so many questions about it.

Come be lazy at Doctolib!


Editor guide