bitsocial-github-alerts

A Telegram bot that posts compact GitHub notifications — pushes, releases, issues, pull requests, and more — to any chat, group, or forum topic. Run by the Bitsocial team for its repositories, but anyone can self-host it.

This is a fork of mhkafadar/notifine, stripped down to GitHub + Telegram only, with compact message formatting and added support for GitHub release notifications. All credit for the original architecture goes to the notifine authors. This repository carries no license of its own because upstream notifine has none; licensing follows upstream.

Features

• Compact messages — pushes show at most 5 commits (first line of each commit message, truncated to 72 chars) plus an "… and N more" line
• Release notifications — one-liner when a release is published, with tag link, release name, pre-release marker, and the first line of the release notes
• Dependabot suppression — events from Dependabot and activity on dependabot/* branches are acknowledged without posting to Telegram
• Explicit push suppression — include [skip github-alerts] in a commit message to acknowledge that push without posting to Telegram
• Supported events: push (incl. branch create/delete and force-push), release, issues (incl. transfers), pull requests, comments (issue/PR review/commit), check runs, workflow runs, wiki edits, ping
• Issue transfers — reported once, from the source repository, naming who moved the issue and where it landed; the destination repository's opened event is dropped because GitHub sends it with the original author as sender
• Branch filtering — ?branch= / ?exclude_branch= glob patterns on the webhook URL
• Authenticated deliveries — verifies HMAC-SHA256 signatures and accepts only the GitHub organization IDs of bitsocialnet, bitsocialforge, and pkcprotocol
• Public repositories only — private repositories and missing or inconsistent visibility are acknowledged without payload logging or Telegram notifications
• Forum topics — run /start inside a Telegram topic to receive notifications there
• Built with Rust (actix-web + teloxide + diesel/Postgres)

Usage

Organization webhooks cover current and future public repositories in bitsocialnet, bitsocialforge, and pkcprotocol. New repositories need no individual webhook or secret setup. Private repositories are excluded from notifications.

To configure an organization's Telegram destination (organization owners only):

1. Open the destination chat or topic with the bot (or add it to a group) and send /start.
2. The bot replies with that chat's webhook URL of the form https://github.bitsocial.net/github/<token>; sending /start alone does not change the organization's destination.
3. In the organization's Settings → Webhooks, configure one webhook with the URL, content type application/json, and the desired events. The hosted setup subscribes to pushes, issues, and releases.
4. Set Secret to the server's GITHUB_WEBHOOK_SECRET, supplied privately by the operator. Keep SSL verification enabled. Never put the secret in the URL or a repository.
5. Verify a successful organization-hook delivery, then disable repository hooks pointing to the same destination to prevent duplicate alerts.

Both JSON and form-encoded deliveries are supported. The server validates the signature over the original request bytes before parsing, filtering, or sending notifications. Missing or invalid signatures return 401; owners outside the allowlist return 403. The allowlist uses immutable organization IDs, so another account cannot gain access by taking an old organization name. Organization-hook pings are also supported. Self-hosters serving other organizations must change the IDs in src/webhooks/github/security.rs.

GitHub sends organization webhooks for private repositories too. After authentication and owner checks, the bot returns 200 without processing or logging their contents. Repository events require private: false; if visibility is present, it must be public. Missing or inconsistent visibility is ignored. Organization pings without a repository remain supported.

Branch filtering

# Only main
https://github.bitsocial.net/github/<token>?branch=main

# Multiple branches and wildcards
https://github.bitsocial.net/github/<token>?branch=main,release/*

# Exclude noisy branches (exclusions take precedence)
https://github.bitsocial.net/github/<token>?exclude_branch=feature/*,dependabot/*

Applies to push, pull request, workflow run, and create/delete events.

Self-hosting

Environment variables

Variable	Required	Description
DATABASE_URL	yes	Postgres connection string
WEBHOOK_BASE_URL	yes	Public base URL GitHub uses to reach the server, e.g. https://github.bitsocial.net
GITHUB_TELOXIDE_TOKEN	yes	Telegram bot token from @BotFather
GITHUB_WEBHOOK_SECRET	yes	Random signing secret of at least 32 bytes, identical to the Secret setting on every connected GitHub webhook
PORT	no	HTTP listen port (default 8080)
ADMIN_LOGS	no	ACTIVE to send admin logs to Telegram (default NOT_ACTIVE)
TELEGRAM_ADMIN_CHAT_ID	no	Chat id that receives admin logs
ADMIN_LOG_LEVEL	no	0–255 verbosity threshold for admin logs (default 50)

Database migrations are embedded and run automatically at startup.

Generate the webhook secret with openssl rand -hex 32 and store it privately. The app refuses to start with a missing or short secret. For an existing deployment, configure the secret on every connected GitHub webhook and in the server environment before deploying signature enforcement. New webhooks also require this secret; copying the URL alone is insufficient. To rotate it, coordinate updates to the server and all connected hooks.

Docker Compose (production)

A production compose file is provided in deploy/docker-compose.yml. It runs the prebuilt image ghcr.io/bitsocialnet/bitsocial-github-alerts:latest next to a Postgres 17 container and binds the app to 127.0.0.1:8090 (put a reverse proxy such as Caddy or nginx in front).

mkdir bitsocial-github-alerts && cd bitsocial-github-alerts
curl -fsSLO https://raw.githubusercontent.com/bitsocialnet/bitsocial-github-alerts/master/deploy/docker-compose.yml
cat > .env <<'ENV'
GITHUB_TELOXIDE_TOKEN=<bot token>
GITHUB_WEBHOOK_SECRET=<random webhook secret>
WEBHOOK_BASE_URL=https://github.example.com
DATABASE_PASSWORD=<random password>
ENV
docker compose up -d

DATABASE_URL is derived from DATABASE_PASSWORD inside the compose file; the other variables come from .env.

Local development

cp .env.example .env   # fill in values
docker compose up -d bitsocial-github-alerts-db
cargo run

Docker image

Images are published to GHCR on every push to master and on version tags:

ghcr.io/bitsocialnet/bitsocial-github-alerts:latest

Credits

Forked from mhkafadar/notifine. Report bugs for this fork by creating an issue.