github_monitor

Powerful real-time GitHub OSINT tool that tracks everything from profile updates and contribution streaks to repository engagement and follower changes - even detecting when you've been blocked, all with instant email and webhook notifications.

🚀 Quick Install

pip install github_monitor

Features

Real-time tracking of GitHub users' activities, including profile and repository changes:
- new GitHub events for the user like new pushes, PRs, issues, forks, releases, reviews etc.
- repository changes such as updated stargazers, watchers, forks, issues, PRs, discussions, description and repo update dates
- added/removed followings and followers
- added/removed starred repositories
- added/removed public repositories
- changes in user name, email, location, company, bio and blog URL
- changes in profile visibility (public to private and vice versa)
- changes in user's daily contributions
- detection when a user blocks or unblocks you
- detection of account metadata changes (such as account update date)
Email and webhook notifications through Discord, ntfy and custom Discord-format integrations for different events
Saving all user activities with timestamps to the CSV file
Clickable GitHub URLs printed in the console & included in email notifications (repos, PRs, commits, issues, releases etc.)
Possibility to control the running copy of the script via signals
Support for Public Web GitHub and GitHub Enterprise
Functional, procedural Python (minimal OOP)

Requirements

Python 3.10 or higher
Libraries: PyGithub (2.8 or newer), requests, python-dateutil, pytz, tzlocal, python-dotenv

Tested on:

macOS: Tahoe, Sequoia, Sonoma, Ventura
Linux: Raspberry Pi OS (Trixie, Bookworm, Bullseye), Ubuntu 24/25, Rocky Linux 8.x/9.x, Kali Linux 2026/2025/2024
Windows: 11, 10

It should work on other versions of macOS, Linux, Unix and Windows as well.

Installation

Install from PyPI

pip install github_monitor

Manual Installation

Download the github_monitor.py file to the desired location.

Install dependencies via pip:

pip install PyGithub requests python-dateutil pytz tzlocal python-dotenv

Alternatively, from the downloaded requirements.txt:

pip install -r requirements.txt

Upgrading

To upgrade to the latest version when installed from PyPI:

pip install github_monitor -U

If you installed manually, download the newest github_monitor.py file to replace your existing installation.

Quick Start

Create a GitHub personal access token then validate and save it through the hidden prompt:

github_monitor --set-github-token

Start monitoring the github_username activities:

github_monitor <github_username>

Or if you installed manually:

python3 github_monitor.py --set-github-token
python3 github_monitor.py <github_username>

To get the list of all supported command-line arguments / flags:

github_monitor --help

Configuration

Configuration File

Most settings can be configured via command-line arguments.

If you want to have it stored persistently, generate a default config template and save it to a file named github_monitor.conf:

# On macOS Linux and Windows Command Prompt (cmd.exe)
github_monitor --generate-config > github_monitor.conf

# On Windows PowerShell (recommended to avoid encoding issues)
github_monitor --generate-config github_monitor.conf

IMPORTANT: On Windows PowerShell, using redirection (>) can cause the file to be encoded in UTF-16, which will lead to "null bytes" errors when running the tool. It is highly recommended to provide the filename directly as an argument to --generate-config to ensure UTF-8 encoding.

Edit the github_monitor.conf file and change any desired configuration options (detailed comments are provided for each).

GitHub Personal Access Token

Go to your GitHub token settings: https://github.com/settings/tokens

Then create a personal access token with the access needed for the accounts and repositories you monitor.

The preferred method validates the token against the configured GitHub API before saving it to .env. Input is hidden and the dotenv file is changed only after GitHub returns the authenticated login:

github_monitor --set-github-token

Use --env-file to select another private settings file:

github_monitor --set-github-token --env-file /path/.env-github_monitor

GitHub Enterprise users can validate against their HTTPS API URL in the same step:

github_monitor --set-github-token --github-url "https://github.example/api/v3"

Fallback methods are:

Set GITHUB_TOKEN as an environment variable
Add GITHUB_TOKEN=... manually to a dotenv file
Pass it for one run with -t or --github-token, which may leave it in shell history or process listings
Hard-code it in the configuration file or source code

If you update GITHUB_TOKEN in the active dotenv file, send a SIGHUP signal to reload it without restarting the tool. More information is available in Storing Secrets and Signal Controls (macOS/Linux/Unix).

GitHub API URL

By default the tool uses Public Web GitHub API URL: https://api.github.com

If you want to use GitHub Enterprise API URL then change GITHUB_API_URL (or use -x flag) to: https://{your_hostname}/api/v3

Events to Monitor

You can limit the type of events that will be monitored and reported by the tool. You can do it by changing the EVENTS_TO_MONITOR configuration option.

By default all events are monitored, but if you want to limit it, then remove the ALL keyword and leave the events you are interested in, for example:

EVENTS_TO_MONITOR=['PushEvent', 'PullRequestEvent', 'IssuesEvent', 'ForkEvent', 'ReleaseEvent', 'DiscussionEvent']

Repositories to Monitor

When tracking repository changes (-j flag), you can limit which repositories will be monitored for detailed changes (stargazers, watchers, forks, issues, PRs, discussions, etc.). You can do it by changing the REPOS_TO_MONITOR configuration option or via the --repos command-line argument (see Monitoring Mode).

By default all repositories are monitored (REPOS_TO_MONITOR = ['ALL']), but if you want to monitor only specific repositories, you can use the 'user/repo_name' format:

REPOS_TO_MONITOR = ['user1/repo1', 'user2/repo2', 'user1/repo3']

This allows you to have different repository lists for different users. When the tool runs for a specific user, it will only monitor repositories where the user matches the user in the list.

Note: When using a specific list (not 'ALL'), newly created repositories will NOT be automatically monitored - only repositories explicitly listed will be monitored.

GitHub API change since 30 Jun 2026: GitHub restricts repository stargazer and watcher identity lists to repository admins and collaborators. When you monitor the account that owns the configured token, github_monitor continues tracking individual stargazers and watchers. When you monitor another account, github_monitor silently skips those identity list requests and tracks only the numeric stargazer and watcher counts. Other repository change tracking remains available. See GitHub's announcement.

Time Zone

By default, time zone is auto-detected using tzlocal. You can set it manually in github_monitor.conf:

LOCAL_TIMEZONE='Europe/Warsaw'

You can get the list of all time zones supported by pytz like this:

python3 -c "import pytz; print('\n'.join(pytz.all_timezones))"

SMTP Settings

If you want to use email notifications functionality, configure SMTP settings in the github_monitor.conf file.

Verify your SMTP settings by using --send-test-email flag (the tool will try to send a test email notification):

github_monitor --send-test-email

Webhook Settings

GitHub Monitor can send activity alerts through Discord or the native ntfy publish API. Webhook alerts work with or without email.

For Discord:

Open the server channel that should receive alerts.
Select Edit Channel, open Integrations then choose Webhooks.
Create a webhook and copy its private URL.
Save it through the hidden prompt:

github_monitor --set-webhook-url

For ntfy.sh or a self-hosted ntfy server, choose a private topic and save its complete HTTPS URL such as https://ntfy.sh/github-monitor-long-random-value. Public ntfy.sh URLs select the ntfy request format automatically. Set the provider in github_monitor.conf for a self-hosted endpoint:

WEBHOOK_PROVIDER = "ntfy"

Topics on the public ntfy.sh service are public unless protected through an account reservation. Treat an unprotected topic name like a password. For a protected topic, store the access token in an environment variable or dotenv file:

NTFY_ACCESS_TOKEN="tk_your_ntfy_access_token"

GitHub Monitor sends this value as Authorization: Bearer <token>. NTFY_ACCESS_TOKEN takes precedence over an Authorization entry in WEBHOOK_HEADERS. Query parameters already present in the topic URL are preserved.

Enable the master switch and select the alert categories you want:

WEBHOOK_ENABLED = True
WEBHOOK_PROVIDER = "discord"
WEBHOOK_PROFILE_NOTIFICATION = True
WEBHOOK_EVENT_NOTIFICATION = True
WEBHOOK_REPO_NOTIFICATION = False
WEBHOOK_REPO_UPDATE_DATE_NOTIFICATION = False
WEBHOOK_CONTRIB_NOTIFICATION = False
WEBHOOK_ERROR_NOTIFICATION = True

Send one test webhook without starting monitoring:

github_monitor --send-test-webhook

For a one-run test, the provider and destination can be overridden without changing the config file:

github_monitor --webhook-provider ntfy --webhook-url "https://ntfy.sh/your-private-topic" --send-test-webhook

Known Discord and ntfy.sh URLs automatically select the matching request format even if the configured provider is stale. Set WEBHOOK_PROVIDER in github_monitor.conf or use --webhook-provider {discord,ntfy} for self-hosted ntfy or compatible endpoints.

A URL passed on the command line may remain visible in shell history or process listings. Prefer --set-webhook-url, an environment variable or a dotenv file for normal setup.

WEBHOOK_USERNAME and WEBHOOK_AVATAR_URL change the sender identity for Discord-format payloads. WEBHOOK_HEADERS adds validated static or placeholder-based headers to Discord and ntfy requests:

WEBHOOK_USERNAME = "GitHub Monitor"
WEBHOOK_AVATAR_URL = "https://example.com/path/avatar.png"
WEBHOOK_HEADERS = {
    "X-Webhook-Title": "{title}",
}

Header values support the same placeholders as WEBHOOK_TEMPLATE. GitHub Monitor validates header names and values before and after placeholder expansion so formatted values cannot introduce line breaks or invalid headers. Prefer NTFY_ACCESS_TOKEN for ntfy bearer authentication. Basic authentication remains available through a custom Authorization header. Long ntfy messages are visibly truncated below ntfy's 4 KB boundary so they remain notifications instead of temporary attachments.

WEBHOOK_TEMPLATE controls the Discord-format request body. It supports {title}, {description}, {version}, {image_url}, {fields}, {fields_str}, {color}, {timestamp}, {username} and {avatar_url}. A dictionary or list is sent as JSON. A string template is sent as the raw request body for compatible custom integrations. Dictionary payloads always replace allowed_mentions with {"parse": []} so alert text cannot trigger Discord mentions.

WEBHOOK_TRANSFORMS applies string methods before the template and headers are rendered:

WEBHOOK_TRANSFORMS = [
    ("title", "upper"),
    ("description", "replace", "**", ""),
    ("description", "strip"),
]

The tuple format is (field_to_target, method_name, *optional_arguments). Invalid templates, avatar URLs, transforms or formatted headers fail before a request is attempted. If a webhook service returns a rate limit or temporary server error, GitHub Monitor retries once and waits at most five seconds. GitHub monitoring continues normally if delivery fails.

Storing Secrets

Prefer --set-github-token for GITHUB_TOKEN and --set-webhook-url for WEBHOOK_URL because both commands keep input hidden. GitHub token setup also validates the secret before saving it. Store SMTP_PASSWORD and NTFY_ACCESS_TOKEN as environment variables or in a dotenv file.

As a fallback, set environment variables using export on Linux/Unix/macOS/WSL systems:

export GITHUB_TOKEN="your_github_classic_personal_access_token"
export SMTP_PASSWORD="your_smtp_password"
export WEBHOOK_URL="https://discord.com/api/webhooks/your_id/your_token"
export NTFY_ACCESS_TOKEN="tk_your_ntfy_access_token"

On Windows Command Prompt use set instead of export and on Windows PowerShell use $env.

Alternatively add them manually to a dotenv file:

GITHUB_TOKEN="your_github_classic_personal_access_token"
SMTP_PASSWORD="your_smtp_password"
WEBHOOK_URL="https://discord.com/api/webhooks/your_id/your_token"
NTFY_ACCESS_TOKEN="tk_your_ntfy_access_token"

By default the tool will auto-search for dotenv file named .env in current directory and then upward from it.

You can specify a custom file with DOTENV_FILE or --env-file flag:

github_monitor <github_username> --env-file /path/.env-github_monitor

You can also disable .env auto-search with DOTENV_FILE = "none" or --env-file none:

github_monitor <github_username> --env-file none

The final fallback is storing secrets in the configuration file or source code.

Sending a SIGHUP signal reloads GITHUB_TOKEN, SMTP_PASSWORD, WEBHOOK_URL and NTFY_ACCESS_TOKEN from the active dotenv file without restarting the tool.

Usage

Monitoring Mode

To monitor specific user activities and profile changes, simply enter the GitHub username as a command-line argument (github_username in the example below):

github_monitor github_username

It will track all user profile changes (e.g. changed followers, followings, starred repositories, username, email, bio, location, blog URL, number of repositories) and also all GitHub events (e.g. new pushes, PRs, issues, forks, releases etc.).

If you have not saved GITHUB_TOKEN, the -t flag remains available as a one-run fallback. The value may remain in shell history or process listings:

github_monitor github_username -t "your_github_classic_personal_access_token"

By default, the tool looks for a configuration file named github_monitor.conf in:

current directory
home directory (~)
script directory

If you generated a configuration file as described in Configuration, but saved it under a different name or in a different directory, you can specify its location using the --config-file flag:

github_monitor <github_username> --config-file /path/github_monitor_new.conf

If you want to monitor changes to user's public repositories (e.g. new stargazers, watchers, forks, issues, PRs, discussions, changed descriptions etc.) then use the -j flag:

github_monitor github_username -j

By default, only user-owned repos are tracked. To include forks and collaborations, set GET_ALL_REPOS to True or use the -a flag:

github_monitor github_username -j -a

If you want to monitor only specific repositories instead of all user-owned repositories, you can do it via the --repos command-line flag or the REPOS_TO_MONITOR configuration option (see Repositories to Monitor). Use the --repos flag with a comma-separated list of repository names:

github_monitor github_username -j --repos "repo1,repo2,repo3"

This will only monitor detailed changes (stargazers, watchers, forks, issues, PRs, discussions, etc.) for the specified repositories. The --repos flag requires the -j flag to be enabled and overrides the REPOS_TO_MONITOR configuration option.

Note: When using a specific list, newly created repositories will NOT be automatically monitored - only repositories explicitly listed will be monitored.

If you want to track user's daily contributions then use the -m flag:

github_monitor github_username -m

Daily contribution checks read the requested day from a wider 30-day GitHub calendar window. This avoids transient partial counts that narrow GraphQL windows can return.

If for any reason you do not want to monitor GitHub events for the user (e.g. new pushes, PRs, issues, forks, releases etc.), then use the -k flag:

github_monitor github_username -k

The tool runs until interrupted (Ctrl+C). Use tmux or screen for persistence.

You can monitor multiple GitHub users by running multiple instances of the script.

The tool automatically saves its output to github_monitor_<username>.log file. It can be changed in the settings via GITHUB_LOGFILE configuration option or disabled completely via DISABLE_LOGGING / -d flag.

Set ASCII_LOG_SEPARATORS to "Auto" (default) to use ASCII separator-only lines on Windows, "On" to use them on every operating system or "Off" to preserve Unicode separators in logs everywhere. Terminal separators stay Unicode. Log files and all other logged text remain UTF-8.

Listing Mode

There is another mode of the tool that displays various requested information (-r, -g, -f and -l flags).

If you want to display a list of public repositories (with some basic statistics) for the user then use the -r flag:

github_monitor github_username -r

By default, only user-owned repos are listed. To include forks and collaborations, set GET_ALL_REPOS to True or use the -a flag:

github_monitor github_username -r -a

If you want to display a list of repositories starred by the user then use the -g flag:

github_monitor github_username -g

If you want to display a list of followers and followings for the user then use the -f flag.

github_monitor github_username -f

If you want to get the list of recent GitHub events for the user then use the -l flag. You can also add the -n flag to specify how many events should be displayed. By default, it shows the last 5 events.

github_monitor github_username -l -n 10

If you want to not only display, but also save the list of recent GitHub events to a CSV file, use the -l flag with -b indicating the CSV file. As before, you can add the -n flag to specify how many events should be displayed/saved:

github_monitor github_username -l -n 10 -b github_username.csv

Email Notifications

To enable email notifications for all user profile changes (e.g. changes in followers, followings, starred repositories, username, email, bio, location, blog URL and number of repositories):

set PROFILE_NOTIFICATION to True
or use the -p flag

github_monitor github_username -p

To receive email notifications when new GitHub events appear for the user (e.g. new pushes, PRs, issues, forks, releases etc.):

set EVENT_NOTIFICATION to True
or use the -s flag

github_monitor github_username -s

To get email notifications when changes in user repositories are detected (e.g. changes in stargazers, watchers, forks, issues, PRs, discussions, descriptions, etc., except for the update date):

set REPO_NOTIFICATION to True
or use the -q flag

github_monitor github_username -j -q

To be informed whenever changes in the update date of user repositories are detected:

set REPO_UPDATE_DATE_NOTIFICATION to True
or use the -u flag

github_monitor github_username -j -u

The last two options (-q and -u) only work if tracking of repositories changes is enabled (-j).

To be informed about user's daily contributions:

set CONTRIB_NOTIFICATION to True
or use the -y flag

github_monitor github_username -m -y

The -y only works if tracking of daily contributions is enabled (-m).

To disable sending an email on errors (enabled by default):

set ERROR_NOTIFICATION to False
or use the -e flag

github_monitor github_username -e

You can combine all email notifications flags together if needed.

Make sure you defined your SMTP settings earlier (see SMTP settings).

Example email:

Webhook Notifications

Webhook event controls mirror the email categories but work independently:

Event	Config setting	CLI override
Profile changes	`WEBHOOK_PROFILE_NOTIFICATION`	`--webhook-profile`
New GitHub events	`WEBHOOK_EVENT_NOTIFICATION`	`--webhook-events`
Repository changes	`WEBHOOK_REPO_NOTIFICATION`	`--webhook-repo-changes`
Repository update date changes	`WEBHOOK_REPO_UPDATE_DATE_NOTIFICATION`	`--webhook-repo-update-date`
Daily contribution changes	`WEBHOOK_CONTRIB_NOTIFICATION`	`--webhook-daily-contribs`
Monitoring errors	`WEBHOOK_ERROR_NOTIFICATION`	Enable with `--webhook-errors` or disable with `--no-webhook-error-notify`

Use --webhook or --no-webhook to turn all configured webhook alerts on or off for one run. A category override also enables the master webhook switch. For example:

github_monitor github_username --webhook-profile --webhook-events

Repository webhook categories only work with -j or --track-repos-changes. Contribution webhooks only work with -m or --track-contribs-changes. Event webhooks are disabled when -k or --no-monitor-events is used.

The provider and destination can also be overridden for one run:

github_monitor github_username --webhook-provider ntfy --webhook-url "https://ntfy.sh/your-private-topic" --webhook-events

See Webhook Settings for private URL setup, ntfy authentication and advanced payload customization.

CSV Export

If you want to save all GitHub user events, profile changes and repository updates to a CSV file, set CSV_FILE or use -b flag:

github_monitor <github_username> -b github_username.csv

The file will be automatically created if it does not exist.

Check Intervals

If you want to customize the polling interval, use -c flag (or GITHUB_CHECK_INTERVAL configuration option):

github_monitor <github_username> -c 900

It is generally not recommended to use values lower than 10 minutes as new events are very often delayed by GitHub API.

Signal Controls (macOS/Linux/Unix)

The tool has several signal handlers implemented which allow to change behavior of the tool without a need to restart it with new configuration options / flags.

List of supported signals:

Signal	Description
USR1	Toggle email notifications for all user's profile changes (-p)
USR2	Toggle email notifications for new GitHub events (-s)
CONT	Toggle email notifications for user's repositories changes (except for update date) (-q)
PIPE	Toggle email notifications for user's repositories update date changes (-u)
URG	Toggle email notifications for user's daily contributions changes (-y)
TRAP	Increase the user check interval (by 1 min)
ABRT	Decrease the user check interval (by 1 min)
HUP	Reload secrets from .env file

Send signals with kill or pkill, e.g.:

pkill -USR1 -f "github_monitor <github_username>"

As Windows supports limited number of signals, this functionality is available only on Linux/Unix/macOS.

Coloring Log Output with GRC

You can use GRC to color logs.

Add to your GRC config (~/.grc/grc.conf):

# monitoring log file
.*_monitor_.*\.log
conf.monitor_logs

Now copy the conf.monitor_logs to your ~/.grc/ and log files should be nicely colored when using grc tool.

Example:

grc tail -F -n 100 github_monitor_<username>.log

Change Log

See RELEASE_NOTES.md for details.

License

Licensed under GPLv3. See LICENSE.

Name		Name	Last commit message	Last commit date
Latest commit History 261 Commits
.github		.github
assets		assets
grc		grc
tests		tests
.gitignore		.gitignore
.gitleaks.toml		.gitleaks.toml
LICENSE		LICENSE
MANIFEST.in		MANIFEST.in
README.md		README.md
RELEASE_NOTES.md		RELEASE_NOTES.md
github_monitor.py		github_monitor.py
pyproject.toml		pyproject.toml
requirements.txt		requirements.txt

Navigation Menu

Repository files navigation

github_monitor

🚀 Quick Install

Features

Table of Contents

Requirements

Installation

Install from PyPI

Manual Installation

Upgrading

Quick Start

Configuration

Configuration File

GitHub Personal Access Token

GitHub API URL

Events to Monitor

Repositories to Monitor

Time Zone

SMTP Settings

Webhook Settings

Storing Secrets

Usage

Monitoring Mode

Listing Mode

Email Notifications

Webhook Notifications

CSV Export

Check Intervals

Signal Controls (macOS/Linux/Unix)

Coloring Log Output with GRC

Change Log

License

About

Releases

Used by

Contributors

Languages

Folders and files

Latest commit

History

Repository files navigation

github_monitor

🚀 Quick Install

Features

Table of Contents

Requirements

Installation

Install from PyPI

Manual Installation

Upgrading

Quick Start

Configuration

Configuration File

GitHub Personal Access Token

GitHub API URL

Events to Monitor

Repositories to Monitor

Time Zone

SMTP Settings

Webhook Settings

Storing Secrets

Usage

Monitoring Mode

Listing Mode

Email Notifications

Webhook Notifications

CSV Export

Check Intervals

Signal Controls (macOS/Linux/Unix)

Coloring Log Output with GRC

Change Log

License

About

Topics

Resources

Stars

Watchers

Forks

Releases

Used by

Contributors

Languages