How to configure GitHub email reminders for overdue reviews

Reviews that are delayed or overdue can block important work from progressing and create bottlenecks, so it's important to keep on top of them for a more efficient development cycle. GitHub provides email reminders for overdue reviews to help avoid these issues. In this guide, we'll walk through how to configure GitHub email reminders for overdue reviews to keep your team productive.

Step 1: Access your repository's settings

To configure email reminders for overdue reviews, you need access to the repository settings:

1. Navigate to the repository for which you want to set up reminders.
2. Click on the Settings tab at the top of the page.
3. From the left-hand menu, under Code and automation, select Branches.

Here, you’ll see the branch protection rules section. While email reminders aren't configured directly in branch protection, setting up the proper rules will complement the email reminders for overdue reviews.

Step 2: Set up branch protection rules for review requirements

Before you can enable email reminders, make sure you have branch protection rules in place that require reviews before a pull request (PR) is merged:

1. In the Branch protection rules section, click on Add rule.
2. Enter the branch name (for example, main) that you want to protect.
3. Check the option Require pull request reviews before merging.
4. Set the number of required reviews and other optional settings, such as dismissing stale reviews if changes are pushed.
5. Click Create to save your settings.

These rules ensure that no code can be merged into critical branches without the necessary reviews.

Step 3: Enable email notifications for overdue reviews

GitHub doesn't provide a direct setting called "overdue review reminders," but you can leverage automation and notifications to stay on top of pending reviews. Here's how you can set up email reminders:

1. Go to your GitHub profile and click on Settings.
2. Under Notifications, click Email preferences.
3. Ensure that you’ve selected the option to receive emails for your repositories and organizations. This ensures you get notifications for assigned reviews.
4. Use tools like GitHub Actions or third-party apps like Graphite to send reminders for overdue reviews. With Graphite, you can set up reminders for:

• Pending reviews that have been open for a specific period
• Reviews with requested changes that need follow-up
• Pull requests with multiple reviews still pending

Example GitHub Action for overdue review reminders

You can also manually set up a GitHub Action to send email reminders for overdue reviews. Here’s a basic example that uses the actions/github-script to scan for overdue reviews:

name: Send overdue review reminders

on:
  schedule:
    - cron: '0 9 * * *' # Runs daily at 9 AM

jobs:
  reminder:
    runs-on: ubuntu-latest
    steps:
      - name: Check for overdue reviews
        uses: actions/github-script@v6
        with:
          script: |
            const openPulls = await github.pulls.list({
              owner: context.repo.owner,
              repo: context.repo.repo,
              state: 'open'
            });

            const overduePRs = openPulls.data.filter(pr => {
              const timeSinceRequested = new Date() - new Date(pr.requested_reviewers[0]?.requested_at);
              return timeSinceRequested > (2 * 24 * 60 * 60 * 1000); // 2 days
            });

            if (overduePRs.length > 0) {
              overduePRs.forEach(pr => {
                // Send an email notification using a mail server here
              });
            }

This action runs daily and checks for pull requests with pending reviews that have been open for more than two days. You can customize the criteria and integrate an email system to notify reviewers.

Best practices for GitHub email reminders

• Set realistic deadlines for reviews: If you want your team to meet review deadlines, be clear about timeframes. Consider using two-day or three-day deadlines depending on your team's workflow.
• Automate reminders: Tools like GitHub Actions, Slack, or email integration services can ensure no reviews are missed.
• Monitor reviews using GitHub Analytics: You can track review response times and identify bottlenecks in your review process using GitHub's built-in analytics or external tools like Graphite.

Try it for yourself

Setting up email reminders for overdue reviews is good practice for keeping your code review process on track. Although GitHub doesn't have a direct feature for overdue reviews, using a combination of branch protection rules, email notifications, GitHub Actions, and Graphite Notifications will help your team stay productive. Now that you know how to configure reminders and manage reviews, try applying these strategies to your repository and improve your team's collaboration.