github-release-monitor/README.md

GitHub Release Monitor

Bash monitor for GitHub releases, with Telegram notifications and SOCKS5 proxy support.

Requirements

• Bash 4+
• curl with SOCKS5 support
• jq
• flock (util-linux)
• mktemp (coreutils)

Debian:

sudo apt-get install curl jq ca-certificates util-linux

Setup

cp .env.example .env
chmod 600 .env
chmod +x monitor.sh

Set TELEGRAM_BOT_TOKEN and TELEGRAM_CHAT_ID in .env. GITHUB_TOKEN is optional for public repositories. SOCKS5_PROXY can be set to socks5h://127.0.0.1:1080; socks5h resolves DNS through the proxy. The .env file is sourced as Bash: use only trusted local configuration.

Edit repos.json to select GitHub repositories. Initial test set: Lychee, Firefly III and Memos.

Commands

./monitor.sh --test-telegram
./monitor.sh --dry-run --verbose
./monitor.sh --init
./monitor.sh
./monitor.sh --include-prereleases

--test-telegram sends one Telegram test message without querying GitHub or accessing state.json/repos.json.

--init records current releases without notifications; it replaces existing baselines. Use only for first initialization or an intentional reset. Normal first run also initializes missing repositories silently.

--dry-run queries GitHub and displays pending notifications without sending or changing state. On a repository without baseline it prints its current release tags.

--include-prereleases overrides INCLUDE_PRERELEASES=false. To track prereleases continuously, set INCLUDE_PRERELEASES=true in .env.

State is written atomically after each successful Telegram notification. If Telegram accepted a message but its response was lost, a duplicate may be sent next time. The state contains release IDs and grows over time. A bounded GitHub pagination window (GITHUB_PER_PAGE * GITHUB_MAX_PAGES) may miss releases if more are published between checks. For small projects and daily checks this is generally sufficient.

Daily cron

At 09:00 server-local time:

0 9 * * * cd /opt/github-release-monitor && ./monitor.sh >> monitor.log 2>&1

Run the monitor under a dedicated user where possible. Keep .env private and do not commit it. Use ./monitor.sh --test-telegram to verify Telegram and proxy connectivity.

Large release histories

GitHub response pages are processed through temporary files, rather than passed through command-line arguments. The state file is read directly by jq. This prevents Argument list too long for repositories with large release notes.

Run bash -n monitor.sh and ./monitor.sh --dry-run --verbose to verify.

Release notes and retention

repos.json uses owner/repo names (legacy full GitHub URLs remain accepted). TELEGRAM_INCLUDE_CHANGELOG=true includes a shortened release body in Telegram messages. TELEGRAM_CHANGELOG_MAX_LENGTH=1800 limits the changelog; Telegram messages are capped at 4096 characters. STATE_MAX_IDS=500 bounds stored release IDs per repository. Keep this larger than the number of releases that may appear in the fetched pages; old releases returning after pruning may otherwise be notified again.

GitHub HTTP 403/429 responses log rate-limit headers and fail without changing the repository state. Mid-pagination errors also fail the repository without partially processing it. Tags without GitHub releases are not tracked.