77 lines
3.3 KiB
Markdown
77 lines
3.3 KiB
Markdown
# 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:
|
|
|
|
```bash
|
|
sudo apt-get install curl jq ca-certificates util-linux
|
|
```
|
|
|
|
## Setup
|
|
|
|
```bash
|
|
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
|
|
|
|
```bash
|
|
./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:
|
|
|
|
```cron
|
|
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.
|