A lightweight, self-hosted Telegram bot that delivers real-time notifications from your GitHub and GitLab repositories to a Telegram forum chat β every kind of event in its own topic.
Why? Because sometimes you don't want to check email or open an app β you just want a message when something happens in your repo.
- π 19 event types from GitHub and GitLab: pushes, tags, pull/merge requests, reviews, issues, comments, releases, CI pipelines, stars, forks
- π Forum topics: Stars, Pushes, Pull Requests, Issues, Releases and CI/CD are created automatically
- π Signed webhooks: GitHub HMAC-SHA256 signatures and GitLab secret tokens are verified
- π Per-chat language: English and Russian, switchable with
/lang - π§© Single static binary: embedded translations, pure-Go SQLite, no runtime dependencies
- π§ One-command Linux install as a hardened systemd service, or run it with Docker
- π Self-hosted GitLab and self-hosted Telegram Bot API server supported
- Screenshots
- Supported events
- Quick start
- Installation on Linux (systemd)
- Running with Docker
- Building from source
- Bot commands
- Environment variables
- Web panel
- Monitoring
- Webhook security
- How notifications are routed
- HTTPS with a reverse proxy
- Project structure
- Development
- Troubleshooting
| New commits | New star |
|---|---|
![]() |
![]() |
| Automatic forum setup | Connecting a repository |
|---|---|
![]() |
![]() |
| Event | Reported actions | Topic |
|---|---|---|
push |
new commits, force push, branch created/deleted, tag created/deleted | π Pushes |
pull_request |
opened (incl. draft), closed, merged, reopened, ready for review | π Pull Requests |
pull_request_review |
approved, changes requested, commented | π Pull Requests |
issues |
opened, closed (incl. "not planned"), reopened | π Issues |
issue_comment |
new comment on an issue or pull request | π Issues |
release |
published release / pre-release | π¦ Releases |
workflow_run |
completed GitHub Actions run: success, failure, cancelled | βοΈ CI/CD |
star |
starred, unstarred | β Stars |
fork |
repository forked | β Stars |
ping |
webhook created (setup confirmation) | General |
| Event | Reported actions | Topic |
|---|---|---|
Push Hook |
new commits, branch created/deleted | π Pushes |
Tag Push Hook |
tag created/deleted | π Pushes |
Merge Request Hook |
opened (incl. draft), closed, merged, reopened, approved | π Pull Requests |
Issue Hook, Confidential Issue Hook |
opened, closed, reopened | π Issues |
Note Hook, Confidential Note Hook |
comment on an issue, merge request or commit | π Issues |
Pipeline Hook |
finished pipeline: success, failed, canceled | βοΈ CI/CD |
Release Hook |
release created | π¦ Releases |
Noisy actions (labels, assignments, edits, PR synchronization, in-progress pipelines, β¦) are intentionally skipped.
Events the bot does not know (e.g. check_suite, deployment) are ignored, so you can safely select
"Send me everything" on GitHub. Set NOTIFY_UNKNOWN_EVENTS=true to get a short message for them instead.
- Open @BotFather and send
/newbot - Choose a name and a username
- Copy the token
- Create a Telegram group and enable Topics (group settings β Topics)
- Add your bot to the group
- Make the bot an administrator with the Manage topics right
Regular groups and private chats work too, but all notifications then arrive in one chat without topics.
Pick one:
- Linux server (recommended):
curl -fsSL https://raw.githubusercontent.com/marensovich/GitHub-GitLab-Notifier/master/scripts/install.sh | sudo bashβ see Installation on Linux - Docker: see Running with Docker
- From source: see Building from source
The bot must be reachable from the internet (GitHub/GitLab send webhooks to it). Set DOMAIN to your public domain
or IP (with port, if you don't use a reverse proxy).
In the forum group, send:
/configure
/connect https://github.com/your-username/your-repo
/configure asks two questions with buttons β whether to create a topic per event type (forum chats only) and
which look to use β and /connect replies with the webhook URL and a secret.
Message look. The new look uses Telegram rich messages: a heading, a compact table of details, collapsible
commit and file lists and coloured buttons. It needs an up-to-date official Telegram app; old and third-party
clients show it as an unsupported message. If your chat reads notifications there, pick Classic in
/configure β the same information as plain formatted text with inline buttons. RICH_MESSAGES=false sends every
chat the classic look.
GitHub: repository β Settings β Webhooks β Add webhook
| Field | Value |
|---|---|
| Payload URL | URL from /connect |
| Content type | application/json |
| Secret | secret from /connect |
| Events | Send me everything (or pick the ones you need) |
GitLab: project β Settings β Webhooks β Add new webhook
| Field | Value |
|---|---|
| URL | URL from /connect |
| Secret token | secret from /connect |
| Triggers | Push, Tag push, Merge request, Issues, Comments, Pipeline, Releases |
GitHub immediately sends a ping event β a "Webhook connected" message appears in the chat. π
scripts/install.sh installs the bot as a systemd service that starts on boot and restarts automatically on failure.
It works on any systemd-based distribution (Debian, Ubuntu, Fedora, RHEL/Rocky/Alma, Arch, openSUSE, Raspberry Pi OS)
on amd64, arm64 and armv7 (32-bit Raspberry Pi).
Latest release, interactive setup:
curl -fsSL https://raw.githubusercontent.com/marensovich/GitHub-GitLab-Notifier/master/scripts/install.sh | sudo bashFrom a cloned repository (builds from source, requires Go 1.26+):
git clone https://github.com/marensovich/GitHub-GitLab-Notifier.git
cd GitHub-GitLab-Notifier
sudo ./scripts/install.sh install --from-sourceUnattended (e.g. Ansible, cloud-init) β settings come from environment variables:
sudo BOT_TOKEN=123456:ABC... TELEGRAM_BOT_USERNAME=MyGitBot DOMAIN=bot.example.com USE_HTTPS=true \
./scripts/install.sh install --non-interactiveThe installer:
- downloads the release binary for your architecture (or builds it / takes
--binary <path>); - creates the unprivileged system user
notifier; - asks for the bot token, port, domain, language, β¦ and writes the config;
- installs and enables the
github-gitlab-notifiersystemd unit, starts it and checks/health.
| What | Where |
|---|---|
| Binary | /opt/github-gitlab-notifier/github-gitlab-notifier |
| Configuration | /etc/github-gitlab-notifier/notifier.env (0640) |
| Database | /var/lib/github-gitlab-notifier/notifier.db |
| Unit | /etc/systemd/system/github-gitlab-notifier.service |
sudo systemctl status github-gitlab-notifiersudo systemctl restart github-gitlab-notifier # after editing the configsudo journalctl -u github-gitlab-notifier -f # live logssudo ./scripts/install.sh update # new version, automatic rollback if it fails to startsudo ./scripts/install.sh uninstall --purge # remove everything incl. config and database| Option | Description |
|---|---|
--version vX.Y.Z |
Install a specific release instead of the latest |
--from-source |
Build from the local checkout with Go |
--binary <path> |
Install an already built binary |
--non-interactive |
Never prompt; read settings from environment variables |
--purge |
With uninstall: also delete configuration, data and user |
The unit is sandboxed (ProtectSystem=strict, ProtectHome, PrivateTmp, NoNewPrivileges, no capabilities, only
the data directory writable). Ports below 1024 get only CAP_NET_BIND_SERVICE.
A ready image for linux/amd64, linux/arm64 (Raspberry Pi 4/5, ARM VPS) and linux/arm/v7 is published to
GitHub Container Registry: ghcr.io/marensovich/github-gitlab-notifier (distroless, non-root, ~24 MB).
With Docker Compose (uses the docker-compose.yml from this repository):
cp .env.example .env # fill in BOT_TOKEN, DOMAIN, ...
docker compose up -dOr with plain Docker:
docker run -d --name notifier --restart unless-stopped \
--env-file .env -p 8080:8080 -v notifier-data:/data \
ghcr.io/marensovich/github-gitlab-notifier:latest| Tag | What |
|---|---|
latest |
Latest stable release |
1.1, 1.1.0 |
A minor line (gets patch updates) or an exact version |
edge |
Latest development build β may be unstable |
The database is stored in the /data volume. Logs: docker compose logs -f. Update: docker compose pull && docker compose up -d. To build the image yourself from a checkout: docker compose up -d --build.
Requires Go 1.26+.
git clone https://github.com/marensovich/GitHub-GitLab-Notifier.git
cd GitHub-GitLab-Notifier
cp .env.example .env # edit it
make build
./GitHub-GitLab-NotifierExpected output:
β
Storage initialized (SQLite)
β
Bot using direct connection
β
Bot @YourGitBot registered. Session active
π Bot @YourGitBot started, listening for commands...
β
Dispatcher initialized with 19 handlers
π Server listening on 0.0.0.0:8080 (version v0.1.0)
Command-line flags:
| Flag | Description |
|---|---|
--config <path> |
Path to the .env file (default .env) |
--db <path> |
SQLite database path (overrides DB_PATH) |
--lang en|ru |
Default language (overrides BOT_LANG) |
--version |
Print version and exit |
Pre-built binaries for Linux, macOS, Windows and FreeBSD are attached to every release.
| Command | Description |
|---|---|
/start |
Welcome message and quick start |
/help |
List of commands |
/configure |
Set up topics (forums) and the message look with buttons; run again to change |
/connect <url> |
Connect a repository: returns webhook URL, secret and instructions |
/disconnect <url> |
Disconnect a repository from this chat |
/status |
Chat settings, topics, connected repositories, version |
/lang en / /lang ru |
Change the language of this chat |
/version |
Bot version |
The commands also appear in Telegram's Menu button.
| Variable | Required | Default | Description |
|---|---|---|---|
BOT_TOKEN |
Yes | β | Telegram bot token from @BotFather |
TELEGRAM_BOT_USERNAME |
No | β | Bot username without @ (informational) |
DOMAIN |
YesΒΉ | β | Public domain or IP:port used in the webhook URL from /connect |
USE_HTTPS |
No | true |
Use https:// in the webhook URL |
SERVER_ADDRESS |
No | all interfaces | Listen address (127.0.0.1 behind a reverse proxy) |
SERVER_PORT |
No | 8080 |
HTTP port for webhooks |
BOT_LANG |
No | en |
Default language (en, ru); each chat can change it with /lang |
CHAT_ID |
No | β | Fallback chat used while no chat is configured |
WEBHOOK_SECRET |
No | β | Global secret; when set, unsigned webhooks are rejected |
DB_PATH |
No | data/notifier.db |
SQLite database file |
NOTIFY_UNKNOWN_EVENTS |
No | false |
Post a short message for unsupported events |
RICH_MESSAGES |
No | true |
Allow Telegram rich messages; false sends every chat the classic look |
DELIVERIES_RETENTION_DAYS |
No | 14 |
Days to keep the webhook delivery log; 0 keeps it forever |
PROXY_ENABLED |
No | false |
Use a proxy for the Telegram API |
PROXY_HOST |
No | β | Proxy host |
PROXY_PORT |
No | β | Proxy port |
PROXY_TYPE |
No | HTTP |
HTTP or SOCKS (SOCKS5) |
TELEGRAM_API_URL |
No | β | Self-hosted Telegram Bot API server |
PANEL_ADDRESS |
No | β (disabled) | Local web panel address, e.g. 127.0.0.1:8081 β see Web panel |
PANEL_ALLOW_REMOTE |
No | false |
Allow the panel on a non-loopback address |
METRICS_ENABLED |
No | true |
Expose Prometheus metrics at /metrics β see Monitoring |
METRICS_ADDR |
No | webhook port | Separate address for /metrics, e.g. 127.0.0.1:9090 |
ΒΉ Required for /connect to generate the webhook URL.
A small read-only panel shows what the bot is connected to: repositories and the chat each one posts to, whether a webhook secret protects it, and every chat with its topics and which events are routed to them. It is not tied to Telegram and has no login, so it only listens on a loopback address.
Enable it in .env and restart the bot:
PANEL_ADDRESS=127.0.0.1:8081Open it from your computer through an SSH tunnel:
ssh -L 8081:127.0.0.1:8081 user@your-serverthen go to http://localhost:8081.
- The bot refuses to start if
PANEL_ADDRESSis not a loopback address (127.0.0.1,::1,localhost), unlessPANEL_ALLOW_REMOTE=trueβ use that only behind your own authentication. - Requests with a non-loopback
Hostheader are rejected, which blocks DNS rebinding. - Only
GET/HEADare accepted; webhook secrets are never displayed, only whether one is set. - Everything is embedded in the binary β the panel works without internet access.
Health. GET /health (also /healthz and /webhook/health) on the webhook port returns JSON and 200 when
everything works, 503 when a check fails:
{"status":"ok","version":"v1.1.0","uptime_seconds":3600,
"checks":{"db":{"ok":true},"telegram":{"ok":true}}}db pings SQLite; telegram is healthy while the bot has had a successful Telegram API call in the last
3 minutes (it calls getMe once a minute, and every sent message counts), so the endpoint itself never calls
Telegram. A failing check carries its error, for example:
{"status":"fail","version":"v1.1.0","uptime_seconds":900,
"checks":{"db":{"ok":true},"telegram":{"ok":false,"error":"no successful Telegram API call for 4m0s: ..."}}}Metrics. GET /metrics serves Prometheus metrics (turn off with METRICS_ENABLED=false):
| Metric | Type | What |
|---|---|---|
notifier_webhooks_total{platform,event,status} |
counter | Webhooks by result: delivered, ignored, rejected, failed, duplicate |
notifier_webhook_duration_seconds |
histogram | Time to handle a webhook, sending included |
notifier_messages_sent_total{messenger,format,result} |
counter | Send attempts by format (rich / classic): ok, error (not delivered) or retried (a later attempt replaced it) |
notifier_rich_fallbacks_total |
counter | Rich messages rejected by Telegram and sent as classic ones |
notifier_build_info{version}, notifier_start_time_seconds |
gauge | Version and start time |
Repository URLs are never used as labels. Event names that do not look like real ones, and new ones beyond
500 label sets, are counted as event="other".
On a public server, keep the metrics off the webhook port:
METRICS_ADDR=127.0.0.1:9090# prometheus.yml
scrape_configs:
- job_name: notifier
static_configs:
- targets: ["127.0.0.1:9090"]A ready Grafana dashboard is in docs/grafana-dashboard.json
(Dashboards β New β Import).
Every repository connected with /connect gets its own random secret:
- GitHub signs each delivery with it (
X-Hub-Signature-256, HMAC-SHA256) β the bot verifies the signature; - GitLab sends it in
X-Gitlab-Tokenβ the bot compares it in constant time.
A request with a wrong signature/token is rejected with 401. Webhooks created without a secret keep working,
unless you set the global WEBHOOK_SECRET β then every webhook must be signed with either the repository secret or
WEBHOOK_SECRET. This is recommended for public servers.
Each incoming webhook is written to a delivery log in the database β only metadata (delivery ID, event, repository,
result, time), never the payload. If GitHub (Redeliver) or GitLab (Resend request, automatic retries) sends a
delivery that was already posted, the bot answers 200 DUPLICATE and posts nothing. A delivery whose messages all
failed to send is not treated as delivered, so redelivering it tries again. The delivery ID comes from
X-GitHub-Delivery, and from Idempotency-Key or X-Gitlab-Event-UUID on GitLab; requests without one are never
dropped. The log is pruned after DELIVERIES_RETENTION_DAYS (14 by default).
- The repository URL is taken from the payload (
repository.html_url/project.web_url). - If the repository was connected with
/connect, the message goes only to that chat. Otherwise it goes to every configured chat, or toCHAT_IDif there are none. - The event is formatted in each chat's language.
- If the chat uses topics, the message is posted to the topic mapped to the event category; if the topic was
deleted, it falls back to the General topic. A chat that chose "no topics" in
/configuregets everything in the main chat. - The message is sent in the look the chat chose. A rich message that Telegram rejects is sent again in the classic look.
GitHub and GitLab recommend HTTPS for webhooks. Run the bot on localhost and put a reverse proxy in front of it:
Caddy (automatic Let's Encrypt certificates):
bot.example.com {
reverse_proxy 127.0.0.1:8080
}
nginx:
server {
listen 443 ssl;
server_name bot.example.com;
# ssl_certificate ... / ssl_certificate_key ...
location /webhook {
proxy_pass http://127.0.0.1:8080;
proxy_set_header Host $host;
}
}Then set SERVER_ADDRESS=127.0.0.1, DOMAIN=bot.example.com and USE_HTTPS=true.
.
βββ main.go # entry point: config, wiring, graceful shutdown
βββ locales/ # translations (embedded into the binary)
βββ internal/
β βββ bot/ # Telegram bot: commands, /configure, sending
β βββ dispatcher/ # routes an event to its handler
β βββ handler/ # one handler per GitHub/GitLab event + formatting
β β βββ testdata/ # payload fixtures + .golden messages (<platform>/<event>/<case>)
β βββ i18n/ # translation loading and lookup
β βββ platform/ # platforms, event types, topics
β βββ server/ # HTTP webhook endpoint, signatures, routing
β βββ web/ # local read-only web panel (templates and CSS embedded)
βββ storage/ # SQLite: chats, topics, repos, event mapping
βββ scripts/install.sh # Linux systemd installer
βββ Dockerfile, docker-compose.yml
βββ .github/workflows/ # CI and release pipelines
SQLite file (DB_PATH, default data/notifier.db):
| Table | Description |
|---|---|
chats |
Configured chats: language, look, topics on/off |
topics |
Created forum topics |
repos |
Connected repositories and secrets |
event_mapping |
Event category β topic, per chat |
make help # list all targets
make test # run tests
make golden # regenerate handler golden files after an intended message change
make lint # gofmt + go vet + shellcheck
make run # run locally with .envWant another event? Adding a handler takes about 50 lines of Go β see CONTRIBUTING.md.
| Problem | Solution |
|---|---|
| Topics are not created | The bot must be an administrator with the Manage topics right |
/configure does not offer topics |
Enable Topics in the group settings, then run /configure again |
| Messages show as "unsupported" | The client is old or third-party: pick Classic in /configure |
| Webhook shows a delivery error on GitHub | The URL must be reachable from the internet β check DOMAIN, port, firewall |
GitHub shows 401 Unauthorized |
The webhook secret does not match the one from /connect (or WEBHOOK_SECRET) |
| Notifications go to the General topic | Run /configure again and choose Create topics β it creates missing topics and restores the mapping |
| No message for an event | Check that the event is supported and selected in the webhook settings |
Wrong address in /connect output |
Set DOMAIN (and USE_HTTPS) in the configuration |
| Bot can't connect to Telegram | Configure PROXY_* or TELEGRAM_API_URL |
| Service does not start | sudo journalctl -u github-gitlab-notifier -n 50 |
- Go β single static binary, cross-compiled for every platform
- telego β Telegram Bot API client
- modernc.org/sqlite β pure Go SQLite, no CGO
- godotenv β
.envconfiguration
MIT Β© marensovich



