AlertHub

AlertHub is a lightweight, self‑hosted notifier built in Node.js 20+ that aggregates change events from GitHub, GitLab, and arbitrary third‑party sources. At its core, it functions as a watcher that polls repository APIs for releases, tags, commits, and issues, then pushes the events to multiple downstream channels—email, PushBullet, PushOver, Telegram, or an RSS feed. The tool is intentionally minimalistic: no GUI, a single binary entry point, and a configuration‑driven runtime that can be started as a background service or inside Docker containers.

Key Features

• Multi‑source monitoring – GitHub releases, tags, commits; GitLab tags/commits; arbitrary HTTP endpoints for third‑party feeds.
• Flexible notification channels – SMTP, PushBullet, PushOver, Telegram bots, and a self‑served RSS feed.
• Aggregated RSS – All watched events are merged into a single chronological feed, ideal for IFTTT or any RSS reader.
• Container‑friendly – A Makefile exposes Docker‑based commands (make install, make start) that eliminate the need for a local Node.js installation.

Technical Stack

The lack of a database keeps AlertHub’s footprint small, but also means that scaling horizontally requires external coordination (e.g., a shared state file or message broker). For most use cases, a single instance suffices; for high‑volume environments, developers can replace the in‑memory store with Redis or a lightweight SQL database and adjust the polling logic accordingly.

Core Capabilities & APIs

AlertHub exposes a single HTTP endpoint (/rss) that serves the aggregated feed. The internal API is not meant for external consumption but can be extended via the plugin system (see below). Developers can:

• Add or remove watches by editing config.yml and triggering a reload (SIGUSR2).
• Query current state by inspecting state.json, which records the last processed event per source.
• Hook custom actions by implementing a small middleware in index.js that listens to the onEvent emitter.

Deployment & Infrastructure

• Self‑hosting – Clone the repo, set environment variables, and run make start.
• Containerization – The provided Dockerfile builds an image that can be deployed on any container platform (Docker Compose, Kubernetes).
• Scalability – While the application is single‑threaded, it can be replicated behind a load balancer if combined with a shared state store.
• Resource footprint – Roughly 50 MiB image size, < 10 mCPU usage, making it suitable for Raspberry Pi or cloud VPS instances.

Integration & Extensibility

AlertHub’s modular architecture allows developers to extend functionality:

• Plugins – Drop a .js file into the plugins/ directory; it receives event objects and can push to custom services.
• Webhooks – The RSS feed can be consumed by any system that supports Atom/RSS, enabling integration with CI/CD pipelines or notification dashboards.
• Custom notifications – Replace the default email transporter with a local MTA or use an external API (SendGrid, Mailgun) by editing the SMTP section of .env.

Developer Experience

• Configuration – Human‑readable YAML for watches, straightforward .env variables for secrets.
• Documentation – The README covers all commands, environment setup, and Docker usage; inline comments in source files aid comprehension.
• Community – The project is hosted on GitHub with an active issue tracker; contributors can submit pull requests for new sources or notification channels.
• Testing – A comprehensive test suite (make test) covers API polling logic and notification delivery, encouraging confidence when extending the codebase.

Use Cases

Advantages Over Alternatives

• No external service dependency – Unlike third‑party aggregators, AlertHub runs entirely on your own infrastructure.
• Fine‑grained watch control – Select specific event types (e.g., only releases) per repository, something GitHub’s native watch feature does not support.
• Open‑source license (MIT)