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

pip install .

Or install in development mode:

pip install -e .

Quick Start

# 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.

ghrel add golang/go              # Track releases
ghrel add zammad/zammad --tags   # Track tags

remove <owner/repo>

Remove a repository and its associated entries.

ghrel remove golang/go

update <owner/repo> [--tags] [--release]

Update the tracking mode for an existing repository.

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).

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.

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

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.