misiektoja/github_monitor
GitHub: misiektoja/github_monitor
Stars: 49 | Forks: 9
# github_monitor
-t "your_github_classic_personal_access_token"
Or if you installed [manually](#manual-installation):
python3 github_monitor.py -t "your_github_classic_personal_access_token"
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
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 Apps settings: [https://github.com/settings/apps](https://github.com/settings/apps)
Then click **Personal access tokens → Tokens (classic) → Generate new token (classic)**.
Provide the `GITHUB_TOKEN` secret using one of the following methods:
- Pass it at runtime with `-t` / `--github-token`
- Set it as an [environment variable](#storing-secrets) (e.g. `export GITHUB_TOKEN=...`)
- Add it to [.env file](#storing-secrets) (`GITHUB_TOKEN=...`) for persistent use
- Fallback: hard-code it in the code or config file
If you store the `GITHUB_TOKEN` in a dotenv file you can update its value and send a `SIGHUP` signal to reload the file with the new token without restarting the tool. More info in [Storing Secrets](#storing-secrets) and [Signal Controls (macOS/Linux/Unix)](#signal-controls-macoslinuxunix).
### GitHub API URL
By default the tool uses Public Web GitHub API URL: [https://api.github.com](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']
### 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, etc.). You can do it by changing the `REPOS_TO_MONITOR` configuration option or via the `--repos` command-line argument (see [Monitoring Mode](#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.
### 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
### Storing Secrets
It is recommended to store secrets like `GITHUB_TOKEN` or `SMTP_PASSWORD` as either an environment variable or in a dotenv file.
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"
On **Windows Command Prompt** use `set` instead of `export` and on **Windows PowerShell** use `$env`.
Alternatively store them persistently in a dotenv file (recommended):
GITHUB_TOKEN="your_github_classic_personal_access_token"
SMTP_PASSWORD="your_smtp_password"
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 --env-file /path/.env-github_monitor
You can also disable `.env` auto-search with `DOTENV_FILE = "none"` or `--env-file none`:
github_monitor --env-file none
As a fallback, you can also store secrets in the configuration file or source code.
## 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 set `GITHUB_TOKEN` secret, you can use `-t` flag:
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](#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 --config-file /path/github_monitor_new.conf
If you want to monitor changes to user's public repositories (e.g. new stargazers, watchers, forks, 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](#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, 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
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_.log` file. It can be changed in the settings via `GITHUB_LOGFILE` configuration option or disabled completely via `DISABLE_LOGGING` / `-d` flag.
### 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
-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 -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 "
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](https://github.com/garabik/grc) to color logs.
Add to your GRC config (`~/.grc/grc.conf`):
# monitoring log file
.*_monitor_.*\.log
conf.monitor_logs
Example:
grc tail -F -n 100 github_monitor_.log
## Change Log
See [RELEASE_NOTES.md](https://github.com/misiektoja/github_monitor/blob/main/RELEASE_NOTES.md) for details.
## License
Licensed under GPLv3. See [LICENSE](https://github.com/misiektoja/github_monitor/blob/main/LICENSE).
