ARIA/github_release_monitor
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Initial commit: GitHub Release Monitor CLI tool

Browse Source 
CLI tool that tracks GitHub releases or tags from user-defined repositories
and exposes them as a subscribable RSS 2.0 feed.

Features:
- Track releases or tags per repository
- SQLite storage with automatic deduplication
- RSS 2.0 feed with markdown-stripped release notes
- Built-in HTTP server for local feed access
- Rate-limit-aware GitHub API client
- 64 passing tests
This commit is contained in:
ARIA
2026-07-28 11:56:10 +02:00
commit 2a5f11bd9b
18 changed files with 2117 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+181
View File
@@ -0,0 +1,181 @@
# GitHub Release Monitor
A CLI tool that tracks GitHub releases or tags from user-defined repositories and exposes them as a subscribable RSS feed.
Some repositories (e.g., Zammad) only use git tags without creating GitHub releases — both modes are supported.
## Features
- Track **releases** or **tags** per repository
- SQLite storage with automatic deduplication
- RSS 2.0 feed with markdown-stripped release notes
- Built-in HTTP server for local feed access
- Rate-limit-aware GitHub API client
- Configurable via environment variables and CLI flags
## Installation
```bash
pip install .
```
Or install in development mode:
```bash
pip install -e .
```
## Quick Start
```bash
# Set your GitHub token (optional, increases rate limit from 60/h to 5000/h)
export GH_TOKEN=your_token
# Add repositories to track
ghrel add golang/go # Track releases (default)
ghrel add zammad/zammad --tags # Track tags
# Fetch latest releases/tags
ghrel check
# List tracked repositories
ghrel list
# Start the RSS feed server
ghrel serve
```
The RSS feed is available at `http://127.0.0.1:8080/feed.xml`.
## CLI Commands
```
ghrel # Main command
├── --version # Show version
├── --verbose / -v # Enable verbose/debug output
├── --quiet / -q # Suppress non-essential output
├── --db-path <path> # Override database path
├── add <owner/repo> [--tags] # Add a repository to track
├── remove <owner/repo> # Remove a repository
├── update <owner/repo> [--tags] [--release] # Update tracking mode
├── list # List all tracked repositories
├── check [--since N] # Fetch latest releases/tags
└── serve [--port 8080] [--host 127.0.0.1] # Start HTTP server
```
### `add <owner/repo> [--tags]`
Add a repository to track. Validates the format and pings the GitHub API to verify the repository exists.
```bash
ghrel add golang/go # Track releases
ghrel add zammad/zammad --tags # Track tags
```
### `remove <owner/repo>`
Remove a repository and its associated entries.
```bash
ghrel remove golang/go
```
### `update <owner/repo> [--tags] [--release]`
Update the tracking mode for an existing repository.
```bash
ghrel update zammad/zammad --tags
ghrel update zammad/zammad --release
```
### `list`
Display tracked repositories with entry counts and last check time.
```
REPO MODE ENTRIES LAST CHECKED
golang/go release 12 2025-01-15 10:30
zammad/zammad tag 8 2025-01-15 10:30
```
### `check [--since N]`
Fetch latest releases or tags for all tracked repositories. With `--since`, only fetch entries published in the last N hours (e.g., `--since 24h`).
```bash
ghrel check # Fetch all new entries
ghrel check --since 24h # Only entries from the last 24 hours
```
### `serve [--port PORT] [--host HOST]`
Start the HTTP server.
```bash
ghrel serve # Default: 127.0.0.1:8080
ghrel serve --port 9090 --host 0.0.0.0 # Custom port and host
```
## Configuration
| Setting | Default | Override |
|---------------|----------------------------|-------------------|
| `db_path` | `~/.config/ghrel/repos.db` | `--db-path` flag |
| `gh_token` | `GH_TOKEN` env var | — |
| `server_host` | `127.0.0.1` | `--host` flag |
| `server_port` | `8080` | `--port` flag |
## RSS Feed
The feed follows RSS 2.0 specification:
- **Title**: `GitHub Release Monitor`
- **Items**: Sorted by `published_at` (newest first), capped at 50 items
- **Release entries**: Title from release name, description from markdown-stripped body (truncated at 300 characters)
- **Tag entries**: Title from tag name, description as `Tag {tag_name}`
## Architecture
```
┌──────────────────────────────────────────────────┐
│ CLI Interface │
│ (add, remove, update, list, check, serve) │
├──────────────────────────────────────────────────┤
│ Core Logic │
│ ┌──────────────┐ ┌──────────────┐ ┌────────┐ │
│ │ config.py │ │ db.py │ │github.py│ │
│ │ (defaults, │ │ (sqlite3) │ │(httpx) │ │
│ │ env vars) │ │ │ │ │ │
│ └──────────────┘ └──────┬───────┘ └───┬────┘ │
│ │ │ │
│ ┌────────▼──────────────▼────┐ │
│ │ rss.py │ │
│ │ (xml.etree + markdown) │ │
│ └──────────────┬─────────────┘ │
│ │ │
│ ┌──────────────▼─────────────┐ │
│ │ server.py │ │
│ │ (http.server, stdlib) │ │
│ │ (/feed.xml endpoint) │ │
│ └─────────────────────────────┘ │
└──────────────────────────────────────────────────┘
```
## Testing
```bash
pytest
```
## Dependencies
| Package | Purpose |
|--------------|------------------------------------------|
| `httpx` | HTTP client for GitHub API |
| `markdown` | Convert markdown to HTML |
| `bleach` | Strip HTML tags for plain text |
| `pytest` | Testing framework |
| `respx` | Mocking HTTP requests for tests |
No heavy frameworks. `http.server` and `xml.etree.ElementTree` are stdlib.