GitHub Scheduled Reminders

22 May 2023 in Tech

I’ve always struggled to manage my GitHub notifications. Having them pushed to me in real-time is overwhelming, but having a separate inbox to check means that I never remember to look at them.

GitHub notifications can be separated in to two categories for me, periodic and real-time. Periodic are things that need doing, but not right now (a PR is ready to review, for example). Real-time are items where there is a real human interacting with you (someone’s commented or requested changes on your PR).

It turns out that GitHub launched scheduled reminders back in 2020 which is a great fit for this use case. Scheduled reminders allow you to receive reminders at specific times throughout the day in addition to real-time alerts for specific events. You can configure them for yourself, or for a specific GitHub team.

Personal reminders

Personal reminders are linked to your personal GitHub account. That means you configure them in your personal GitHub settings and receive them as a DM from the GitHub bot. Head to your GitHub settings to configure them. You’ll be presented with a list of organisations. Once you choose an org it will ask you to authorize a Slack workspace and configure the days/times that you'd like to be reminded.

GitHub Scheduled Reminder configuration page

I've found that 8:30am and 2:30pm on weekdays is a good schedule for me. It allows me to review PRs before getting back to focused work when I start my day / after lunch. I also enable review requests waiting on my team in addition to those that are assigned specifically to me. This takes care of the period reminders that there are still PR reviews outstanding.

The next thing to configure is real-time alerts. I try to focus on things that need immediate attention, which means I disable notifications when I'm assigned a review (I'll see it in the periodic reminders). Here are the alerts that I do enable:

GitHub Scheduled Reminder - real-time events

I'd also like to enable "Your PR has failed CI checks" but it requires a list of failed check names. I'd love to see the ability to get notified on all check failures so that I can keep my open PRs moving.

Once you press "Create reminder" you'll see your selected reminder times and the connected Slack workspace on your reminders overview:

GitHub Scheduled Reminder - fully configured reminder

Team reminders

You can also configure team reminders in addition to personal reminders. The settings are a little bit different as team reminders don't allow for real-time alerts. They do however have more filters available to control which PRs are shown in the reminder.

To configure team reminders, head to https://github.com/orgs/YOUR_ORGKong/teams and select the team you'd like to receive reminders for. Click Settings in the top right, then Scheduled reminders on the left. You can configure multiple reminders, each going to a different channel. This is useful if you want to direct specific repos to specific channels.

The settings I always enable here are "Ignore drafts" and "Require review requests". This makes sure that only PRs that can be reviewed are in the list of reminders. If you use "require review requests", make sure that you use the CODEOWNERS file to trigger review requests for your team.

GitHub Scheduled Reminder - team reminders

There are some other useful configuration options in here too:

  • Ignore approved pull requests - Only remind the team about PRs that have not yet been approved. I set this to "Ignore with 2 or more" as the PR requires approval from two teams
  • Minimum staleness - This controls how long a PR has to be inactive before you're reminded about it. We set this to 0 hours, but it could be useful if you want to see stale PRs.
  • Ignored labels - This is useful if your PR is awaiting changes from the author. You can add a waiting-for-author label (or use the Issue Management GitHub Action) and exclude any PRs that have that label
  • Required labels - The opposite of the entry above. Some of our PRs have a review scope (e.g. copyedit, tech or SME - that's subject matter expert) to indicate what we should be looking for. We use this option to push review:tech items to a separate channel as the audience for these PRs is much smaller.

What does it look like?

Once you've configured your reminders, you'll start to receive notifications in Slack. These notifications will be broken down by repository, and contain additional metadata such as how old the PR is and how long it's been inactive. Here are a couple of examples.

Example: Personal Reminders

Personal reminders will be sent to you via DM:

GitHub Scheduled Reminder - personal example

Example: Team Reminders

Team reminders will be sent to a specific channel:

GitHub Scheduled Reminder - personal example

If your team have linked their Slack and GitHub accounts, the notification will show their Slack handle rather than their GitHub handle:

GitHub Scheduled Reminder - personal example

Further reading