Clearing GitHub Notifications with a Shell Script: An Introduction to Underutilized GitHub API Endpoints

If you’re an active GitHub user, chances are you’ve experienced notification overload at some point. While GitHub’s notification system helps keep you up to date on all the repositories you follow, it can get overwhelming quickly. Thankfully, GitHub provides a robust API that allows us to manage notifications (among many other things) in ways that are not always obvious in the user interface.

In this post, we’ll cover how to use a simple shell script to clear GitHub notifications using the GitHub API. We’ll also explore some lesser-known and underutilized areas of the GitHub API that can help you automate and streamline your development workflows.

Clearing GitHub Notifications with a Shell Script

Imagine you have a backlog of unread GitHub notifications, and no matter what you do, the notification count won’t clear. Luckily, GitHub provides a dedicated Notifications API that allows developers to interact with their notification feed. Using this API, we can mark notifications as read with a single API call.

Let’s walk through a simple shell script that takes a GitHub Personal Access Token (PAT) as an argument and clears all notifications.

The Shell Script

#!/bin/bash

# Check if the token was passed as an argument
if [ -z "$1" ]; then
  echo "Usage: $0 <GitHub Personal Access Token>"
  exit 1
fi

# GitHub Personal Access Token
TOKEN=$1

# Get the current date and time in ISO 8601 format
now=$(date +%Y-%m-%dT%H:%M:%SZ)

# cURL command to mark all notifications as read
curl -H "Authorization: bearer $TOKEN" \
     -X PUT \
     -H "Accept: application/vnd.github.v3+json" \
     https://api.github.com/notifications \
     -d '{"last_read_at":"'"$now"'"}'

echo "All notifications have been marked as read!"

How It Works

1. Personal Access Token (PAT): The script expects your PAT as an argument. You can create one by following this guide. Make sure it has the appropriate permissions for notifications.

2. Current Timestamp: The script grabs the current date and time in the ISO 8601 format (YYYY-MM-DDTHH:MM:SSZ) to mark notifications as read up to that point.

3. API Call: Using the curl command, the script sends a PUT request to the GitHub API with the last_read_at parameter set to the current timestamp. This effectively marks all notifications as read.

How to Use the Script

1. Save the script to a file, for example, clear_github_notifications.sh.

2. Give the script execution permission by running:
   

   chmod +x clear_github_notifications.sh

1. Run the script and pass your GitHub PAT as an argument:

   ./clear_github_notifications.sh <your-github-personal-access-token>

After running the script, all your notifications will be marked as read, clearing your inbox and resetting the notification count.

Exploring Other Underutilized Areas of the GitHub API

The GitHub API is incredibly powerful, yet many of its features are underutilized by developers. Here are a few lesser-known API endpoints and use cases that can help you take your GitHub automation to the next level.

1. Automating Repository Management with the Repositories API

The Repositories API is a rich part of the GitHub API, yet many people don’t use it to its full potential. Here are some handy things you can do with this API:

• Automatically Archiving Repositories: When a project reaches its end of life, you can archive it automatically. This endpoint allows you to archive a repository by sending a simple API request.

   curl -X PUT -H "Authorization: bearer $TOKEN" \
        https://api.github.com/repos/yourusername/repo-name/archive

• Automatically Creating Repositories: You can automate the creation of repositories using the API. This is great if you manage multiple projects and want to create new repositories based on templates.

   curl -X POST -H "Authorization: bearer $TOKEN" \
        -d '{"name": "new-repo", "auto_init": true}' \
        https://api.github.com/user/repos

2. Managing Workflow Runs with the Actions API

GitHub Actions is a powerful automation tool, but did you know you can manage your workflows directly from the API? The Actions API allows you to list, rerun, or cancel workflow runs.

• Rerun a Workflow: Need to rerun a failed workflow? You can trigger a rerun directly from the API.

   curl -X POST -H "Authorization: bearer $TOKEN" \
        https://api.github.com/repos/yourusername/repo-name/actions/runs/workflow_id/rerun

• Get Workflow Logs: Retrieve logs for a specific workflow run and diagnose issues without even opening the GitHub UI.

   curl -H "Authorization: bearer $TOKEN" \
        https://api.github.com/repos/yourusername/repo-name/actions/runs/workflow_id/logs

3. Tracking Issues and Pull Requests with the Issues API

The Issues API is a lifesaver if you’re tracking multiple projects and issues. With this API, you can:

• Automatically Assign Issues: Automatically assign issues to team members based on predefined criteria.

   curl -X POST -H "Authorization: bearer $TOKEN" \
        -d '{"assignees": ["username"]}' \
        https://api.github.com/repos/yourusername/repo-name/issues/issue_number

• Label Issues: Automatically label issues to prioritize or categorize them for easier tracking.

   curl -X POST -H "Authorization: bearer $TOKEN" \
        -d '{"labels": ["bug", "priority"]}' \
        https://api.github.com/repos/yourusername/repo-name/issues/issue_number/labels

4. Interacting with GitHub Discussions Using the Discussions API

GitHub Discussions is an increasingly popular feature for community engagement, and the Discussions API makes it easy to automate and manage discussions.

• Creating a New Discussion: Use the API to create new discussions for community input or project-related queries.

   curl -X POST -H "Authorization: bearer $TOKEN" \
        -d '{"title": "New Discussion", "body": "Let's talk about this!", "category_id": 123}' \
        https://api.github.com/repos/yourusername/repo-name/discussions

While GitHub’s user interface is powerful, there are plenty of ways to extend and automate your workflows using the GitHub API. Whether you want to clear notifications, automate repository management, rerun workflows, or manage issues and discussions, the API provides endless possibilities.

The simple shell script we provided is just one example of how you can start harnessing the power of the GitHub API. From automating tedious tasks to implementing custom workflows, the GitHub API can transform the way you manage your projects and collaborate with your team.

Start exploring, experiment with different API endpoints, and you’ll soon discover a world of automation opportunities on GitHub!