prune-github-notifications

Prunes GitHub notifications you don't care about, such as automated dependency bumps. 🧹

Usage

CLI

prune-github-notifications can be run on the CLI with an auth token for notifications access:

npx prune-github-notifications

CLI Options

Option	Type	Default	Description
--auth	string	process.env.GH_TOKEN or executing gh auth token	Auth token for GitHub from octokit-from-auth.
--bandwidth	number	6	Maximum parallel requests to start at once.
--createdBy	string[]	-	Thread author regular expressions to additionally filter to.
--label	string[]	-	Issue or pull request label regular expressions to additionally filter to.
--lastCommentBy	string[]	-	Latest comment author regular expressions to additionally filter to.
--help	boolean	false	Prints a usage message and exits.
--reason	string[]	["subscribed"]	Notification reason(s) to filter to, or any to match all reasons.
--title	string[]	["^(?:build|chore)\(deps\): (?:(?:bump|update) .+ to|lock file maintenance)", "^Bump .+ from .+ to .+"]	Notification title regular expressions to filter to.
--watch	number	0	A seconds interval to continuously re-run this on, if truthy.

For example, providing all functional options on the CLI:

npx prune-github-notifications --bandwidth 10 --reason subscribed --title "^chore.+ update .+ to"

Pruning matching titles regardless of notification reason (e.g. review_requested from being a CODEOWNER):

npx prune-github-notifications --reason any

Pruning threads created by a specific bot, regardless of title:

npx prune-github-notifications --reason any --title ".*" --createdBy "^renovate\[bot\]$"

Pruning threads whose issue or pull request has a specific label, regardless of title:

npx prune-github-notifications --reason any --title ".*" --label "^dependencies$"

Pruning your own threads (author reason) whose latest comment is from a specific account:

npx prune-github-notifications --reason author --title ".*" --lastCommentBy "^codecov"

Pruning your own threads whose latest comment is from any [bot] account:

npx prune-github-notifications --reason author --title ".*" --lastCommentBy "\[bot\]$"

Running in watch mode to clear notifications every ten seconds:

npx prune-github-notifications --watch 10

Watch mode logs and retries after a failed run, such as when a network request or gh auth token lookup fails. It exits with the error if three runs in a row fail.

Debug Logging

Set the DEBUG environment variable to prune-github-notifications to log details such as how many notifications were fetched, how many matched the filters, and which threads are being pruned:

DEBUG=prune-github-notifications npx prune-github-notifications

Node.js API

npm i prune-github-notifications

import { pruneGitHubNotifications } from "prune-github-notifications";

await pruneGitHubNotifications({ auth: "gho_..." });

If a process.env.GH_TOKEN is set, then the auth parameter will default to it:

await pruneGitHubNotifications();

Node.js Options

Only auth is required, and only if a GH_TOKEN isn't available.

Option	Type	Default	Description
auth	string	process.env.GH_TOKEN	GitHub authentication token with notifications access.
bandwidth	number	6	Maximum parallel requests to start at once.
createdBy	RegExp[]	-	Thread author regular expressions to additionally filter to.
label	RegExp[]	-	Issue or pull request label regular expressions to additionally filter to.
lastCommentBy	RegExp[]	-	Latest comment author regular expressions to additionally filter to.
reason	Set<string>	Set {"subscribed"}	Notification reason(s) to filter to, or any to match all reasons.
title	RegExp[]	[/^(?:build|chore)\(deps\): (?:(?:bump|update) .+ to|lock file maintenance)/, /^Bump .+ from .+ to .+/]	Notification title regular expressions to filter to.

For example, providing all options to the Node.js API:

await pruneGitHubNotifications({
	auth: "gho_...",
	bandwidth: 10,
	reason: subscribed,
	title: ["^chore.+ update .+ to"],
});

Recipes

Suggested ways to keep prune-github-notifications running so notifications stay pruned without you having to think about it.

GitHub Actions Workflow

A scheduled workflow can prune your notifications on a timer, even when your computer is off. Store a token as a repository secret and run npx prune-github-notifications from a workflow such as .github/workflows/prune-github-notifications.yaml:

jobs:
  prune:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/setup-node@v7
        with:
          node-version: 24
      - env:
          GH_TOKEN: ${{ secrets.PRUNE_GH_TOKEN }}
        run: npx prune-github-notifications

name: Prune GitHub Notifications

on:
  schedule:
    - cron: "*/10 * * * *"
  workflow_dispatch: ~

Some things to know before setting this up:

• The GitHub notifications API only supports personal access tokens (classic) with the notifications scope, not fine-grained tokens. The token is tied to your account, so keep the workflow in a personal repository (private, ideally) rather than one shared with a team.
• The GH_TOKEN environment variable is what --auth defaults to, so no other options are needed to authenticate.
• Scheduled workflows run on a best-effort basis and may be delayed or dropped under high load, especially at the top of each hour. In a public repository, they're also disabled automatically after 60 days without repository activity. The workflow_dispatch trigger lets you run the workflow manually from the Actions tab.

Watch Mode

If you'd rather keep a terminal open, --watch re-runs pruning on an interval without needing an external scheduler:

npx prune-github-notifications --watch 60

Development

See .github/CONTRIBUTING.md, then .github/DEVELOPMENT.md. Thanks! 🧹

Contributors

Josh Goldberg 🔧 🚧 🤔 💻 🐛 🖋 📖 🚇 📆

💝 This package was templated with create-typescript-app using the Bingo framework.