Ops Gateway

(Overview)

Ops Gateway brings two complementary tools into one portfolio story: Ops Ledger prepares operational events, and the Telegram Gateway delivers messages. They remain two repositories and two independent Worker runtimes; this is a shared product direction, not a physical code or deployment merger.

(Origin)

Subscription reminders in SubsTracker started a broader need: one place for notifications from small tools, service health, deployments, GitHub Actions and MonitorFlare. Centralizing the Telegram bot credential avoids distributing it across every caller.

(Delivery boundary)

The Gateway is a stateless Cloudflare Worker exposing GET /health and POST /v1/notify. Bearer authentication accepts a primary credential and a separately scoped Ops Ledger secret. Bot token and chat destination stay in Worker secrets; callers cannot override chat_id, bot_token or token. The relay has no database, KV, D1, queue or frontend.

(Payload discipline)

Plain text passes through unchanged; JSON uses a small allowlist of presentation options. The request body is limited to 64 KiB and the Telegram message to 4,096 characters. Request correlation IDs and minimal structured logs support diagnosis without logging message bodies or credentials. A native adapter handles MonitorFlare monitor.down, monitor.warning and monitor.up events.

(Event ledger)

Ops Ledger receives GitHub push, check_run, deployment, deployment_status and workflow_run events. It verifies HMAC signatures, de-duplicates deliveries, stores event history in D1, normalizes events and enriches them with known commit context. It formats significant notifications upstream and supports both a generic outgoing webhook and a dedicated Telegram Gateway adapter.

(Two paths)

Simple path: MonitorFlare or a small tool → Gateway → Telegram. Complex path: GitHub → Ops Ledger (validate, de-duplicate, store, normalize and format) → Gateway → Telegram. The Ledger adapter uses TELEGRAM_GATEWAY_URL and a scoped TELEGRAM_GATEWAY_TOKEN with X-Notify-Source: ops-ledger. The Gateway does not need to understand GitHub events.

(Boundaries)

The Gateway is a delivery service, not a workflow engine, GitHub event processor or bot framework. Ops Ledger is currently private; the linked Gateway repository is public and MIT-licensed. Any future engineering consolidation is a separate decision. MonitorFlare remains an independent monitoring project and one possible notification source.