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 & Run

New to Python or unsure what is installed? Follow the Python install walkthrough first.

Install from PyPI:

pip install github_monitor

Run the setup wizard:

github_monitor --setup

The wizard asks for the target, the GitHub token and optional notifications. Review the settings before saving them. See Setup & First Run for how to create the GitHub personal access token.

For the manual single-file method, dependencies and upgrade commands, see Installation.

Features

🔍 Activity and Profile Tracking

• GitHub events: Track pushes, pull requests, issues, forks, releases and reviews.
• Profile changes: Detect changes to names, email, location, company, bio, blog URL, visibility and account metadata.
• Connections and contributions: Track followers, followed accounts, daily contributions and blocking or unblocking.

📊 Repository Insights

• Repository lists: Track added or removed public and starred repositories.
• Repository changes: Monitor stars, watchers, forks, issues, pull requests, discussions, descriptions and update dates.
• Removal context: Flag deleted accounts or repositories when reporting removals.
• GitHub links: Open repositories, commits, issues and other activity from console and email links.

🔔 Notifications and History

• Event alerts: Send email, Discord and ntfy notifications with event-specific controls.
• CSV history: Save detected activity and profile changes with timestamps.
• Terminal colours: Customize the theme, with colours disabled when output is redirected.

⚙️ Setup and Configuration

• Guided setup: Configure a target, credentials and alerts with --setup, then check them with --doctor.
• Flexible settings: Use configuration files, dotenv files, environment variables and command-line options.
• Runtime controls: Adjust the running monitor through supported signals.
• GitHub deployments: Connect to public GitHub or GitHub Enterprise.

Common Commands

Use Quick Install & Run above for first-time setup. The table uses PyPI commands. For the manual script equivalents, see Run Individual Commands.

Replace the target placeholders with a GitHub username or complete profile URL. Monitoring requires the GitHub personal access token described in the setup guide.

Running the tool with no arguments offers the wizard if you have not saved a target. If a target is already saved, it starts monitoring that target.

The tool runs until interrupted (Ctrl+C). Use tmux or screen for persistence and run multiple copies to monitor several targets.

For the personal access token, saved targets and notification setup, see the full Setup & First Run guide.

For the events and repositories to monitor, TLS verification, email and webhook setup, see Configuration. For notification choices, listing commands and output files, see Usage.

If a run fails, start with Doctor Preflight.

Documentation

Full documentation is available at misiektoja.github.io/github_monitor:

Change Log

See RELEASE_NOTES.md.

Contributing

Bug reports, documentation fixes and code contributions are welcome. See CONTRIBUTING.md for the development setup, the checks CI enforces and what a change needs before it is merged. Participation is covered by the Code of Conduct.

Security

Report a suspected vulnerability privately through GitHub security advisories, never as a public issue. SECURITY.md covers the reporting process, the supported versions and the security posture of stored credentials and configuration loading.

Maintainers

• misiektoja (@misiektoja)

License

Licensed under GPLv3. See LICENSE. Dependency licenses are listed in THIRD_PARTY_NOTICES.md.

Support

Questions, bug reports and vulnerability reports each have a place, listed in SUPPORT.md.

If the project is useful to you, you can support its development through GitHub Sponsors or Buy Me a Coffee.