GitHub Ntfy

github-ntfy is a lightweight, self‑hosted notification broker written in Rust that watches GitHub and Docker Hub for new releases and forwards those events to a variety of downstream services such as ntfy, Gotify, Discord, and Slack. The core of the application is a long‑running event loop that polls the GitHub and Docker Hub APIs, parses release metadata, and dispatches HTTP POST requests to configured endpoints. By leveraging Rust’s zero‑cost abstractions and async runtime, the binary achieves high throughput with minimal CPU and memory footprint, making it suitable for deployment on resource‑constrained edge devices as well as cloud VMs.

Architecture

• Language & Runtime: Rust 1.70+, using the tokio async runtime for non‑blocking I/O and concurrent polling.
• HTTP Client: reqwest (async) for outbound webhook delivery; hyper underpins the HTTP stack.
• Configuration: Environment variables (via dotenv‑style parsing) expose all runtime options—GitHub token, Docker credentials, notification URLs, timeouts, etc. A single JSON/YAML config file is also supported for advanced setups.
• Data Persistence: Minimal state is stored on disk under /data. The persisted file contains the last processed release SHA for each monitored repository, enabling idempotent operation across restarts.
• Extensibility: The notification layer is pluggable; each destination implements a common trait Notifier. Adding a new provider (e.g., Matrix or Telegram) only requires implementing this trait and registering it in the main loop.

Core Capabilities

• Multi‑source Monitoring: Simultaneously watches arbitrary GitHub repositories and Docker Hub images. Supports both public and private resources via token authentication.
• Event Deduplication: Keeps track of the latest release per source to avoid duplicate notifications.
• Custom Payloads: Allows templating of notification messages using a simple key‑value substitution syntax.
• Rate Limiting & Backoff: Configurable timeout (GHNTFY_TIMEOUT) and exponential backoff for transient API failures.
• Health & Metrics: Exposes a /health endpoint and optional Prometheus metrics for observability.

Deployment & Infrastructure

• Containerization: Official Docker image (breizhhardware/github-ntfy) is multi‑architecture (amd64, arm64, armv7) and can be pulled from Docker Hub. The image runs as a single process exposing port 80 for health checks.
• Self‑Hosting: No external dependencies beyond the notification services’ webhooks. The binary can be compiled from source for bare‑metal or embedded environments.
• Scalability: Horizontal scaling is straightforward—multiple instances can monitor disjoint sets of repositories. For high‑volume scenarios, a load balancer can route health checks to the healthiest node.
• Resource Footprint: A typical instance consumes < 20 MiB RAM and 5–10 CPU cycles when idle, with peaks only during webhook dispatch.

Integration & Extensibility

• Webhook API: Consumers can send POST requests to /trigger (future feature) to force a re‑check of specific repositories.
• Plugin System: The Notifier trait makes it trivial to add new destinations. Example implementations for ntfy, Gotify, Discord, and Slack are included in the source tree.
• Environment‑Driven: All endpoints and credentials are supplied via environment variables, enabling integration with CI/CD pipelines, Kubernetes secrets, or Docker Compose.
• Future Extensions: The roadmap lists support for Telegram, Matrix, and a web onboarding UI, indicating an active development cycle.

Developer Experience

• Documentation: The README covers installation, configuration, and version history. Additional docs reside in CONTRIBUTION.md and inline comments.
• Community & Licensing: Licensed under GPL‑3, the project is maintained by a single contributor (BreizhHardware) with active GitHub and Twitter engagement. Pull requests are welcomed, though the codebase remains relatively small.
• Error Handling: Comprehensive logging (via tracing) with structured JSON output facilitates debugging in production environments.

Use Cases

Advantages

• Performance: Rust’s async runtime delivers low latency and high concurrency compared to the legacy Python version.
• Resource Efficiency: Suitable for ARM devices and minimal cloud instances, reducing operational costs.
• Simplicity: One binary, no external services required beyond webhook endpoints; configuration is purely environment‑driven.
• Extensibility: The notifier trait and templating system allow rapid addition of new channels without touching core logic.
• License: GPL‑3 ensures that any derivative work remains open source, aligning with many organizations’ compliance policies.

In summary, github-ntfy offers a performant, extensible bridge between GitHub/Docker Hub release events and modern notification platforms, packaged in a self‑hosted Rust application that scales from a Raspberry Pi to a cloud VM.