Start with the documentation. Installation and Setup & First Run cover most first-run problems, Configuration explains every setting the tool reads and Troubleshooting covers what to do when a check fails.
For a new install, run github_monitor --setup. Review the complete summary before saving. The wizard keeps private values in a separate dotenv file then offers the read-only doctor preflight after authentication is complete. If no interactive terminal is available, run github_monitor --generate-config github_monitor.conf and follow the manual setup steps in Setup & First Run.
Confirm which version you are running then run the complete read-only preflight for the affected target:
github_monitor --version
github_monitor --doctor <github_target>Most reports come down to an expired or under-scoped GitHub token, an unreachable target, invalid output permissions, an SMTP setup that cannot deliver or a webhook destination the provider no longer accepts. Doctor tells those apart in one report.
When an error includes a recovery code, include that code in the report. Re-run the failing command with --verbose to show decisions and unavailable alerts. Use --debug when the report also needs request, delivery, file, retry or poll timing details. Technical detail is sanitized but you should still review copied output before posting it publicly.
Doctor checks Environment, Configuration, Authentication, Connectivity, Target, Monitoring and Notifications in a fixed order. It writes no files. Each check has a stable [PASS], [WARN], [FAIL] or [SKIP] marker plus a fix and guide for every non-pass result.
The Configuration section resolves LOCAL_TIMEZONE. It reports the detected zone when the setting is Auto and fails when the zone is invalid or cannot be detected.
The Notifications section signs in to the configured SMTP server and validates webhook settings without sending anything. Each ready row lists the alert categories that channel would deliver.
Live colour is enabled by COLORED_OUTPUT and can be disabled with --no-color or NO_COLOR=1. It is also disabled for redirected output, piped stdin and terminals with an unset or dumb TERM. Saved log files never contain ANSI colour sequences.
The terminal sanitizer preserves SGR colour sequences so the tool's own styles survive the output wrapper. It removes cursor movement, screen clearing, title changes, carriage returns and other controls. A remote string that contains a bare SGR sequence may still affect styling until the next reset, but it cannot move the cursor or change terminal state outside SGR styling. Use --no-color when collecting output for a parser that rejects every escape byte.
TRUNCATE_CHARS and --truncate measure plain visible text before colour is added. Install wcwidth when exact width matters for emoji or other wide Unicode characters.
A normal non-interactive run sends no messages. When a configured channel is ready and stdin is interactive, doctor offers a separate default-no prompt for one real email and one real webhook. Declining records [SKIP]. An approved delivery failure records [FAIL] and makes the command exit with status 1.
Include the complete sanitized doctor report in a bug report. Review target names, paths and recipient addresses before posting even though credential values are redacted.
| You want to | Go to |
|---|---|
| Ask a question or discuss an idea | Discussions |
| Report something broken | Bug report |
| Request a capability | Feature request |
| Report a vulnerability | Private security advisory, never a public issue |
| Contribute a change | CONTRIBUTING.md |
Include the version, recovery code, how you installed it (PyPI or manual script), your operating system, the monitored user or repository form you passed and what you expected instead. Attach the relevant part of the monitoring log file, which the tool writes unless you pass --disable-logging.
Never post your GitHub personal access token, SMTP passwords, webhook URLs or a complete configuration file. Redact monitored usernames and private repository names if they matter to you.
This is a project maintained in spare time, so replies are best effort with no response time attached. Only the latest release receives fixes, so reproduce the problem on the current version before reporting it.
If the project is useful to you, you can support its development through GitHub Sponsors or Buy Me a Coffee.