A lightweight, self-hosted Telegram bot that sends real-time notifications from your GitHub and GitLab repositories directly to your Telegram Forum chat.
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.
This bot is designed to work with Telegram Forum Groups (topics enabled). It creates separate topics for each event type:
- ⭐ Stars — new stars on your repository
- 🚀 Pushes — new commits pushed
Regular groups and channels are not supported for automatic topic creation. You can still use them, but all notifications will arrive in the general chat (no topic separation).
- Open your Telegram group settings
- Click Edit → Administrators
- Enable Topics
- Now your group is a Forum
- Open @BotFather
- Send
/newbot - Choose a name and username
- Copy the token you receive
- Create a new Telegram group
- Enable Topics in group settings
- Add your bot to the group
- Make the bot an administrator (required for creating topics)
- Send any message to the bot
- Visit:
https://api.telegram.org/bot<YOUR_BOT_TOKEN>/getUpdates - Find
"chat":{"id":-1001234567890}— this is yourCHAT_ID
git clone https://github.com/marensovich/github-gitlab-notifier.git
cd github-gitlab-notifier
cp .env.example .envEdit .env with your values:
BOT_TOKEN=123456:ABCdefGHIjklMNOpqrsTUVwxyz
TELEGRAM_BOT_USERNAME=YourGitBot
CHAT_ID=-1001234567890
DOMAIN=your-server.com # optional, for webhook URLmake build
./GitHub-GitLab-Notifier --lang=enExpected output:
✅ Bot using direct connection
✅ Bot @YourGitBot registered. Session active
✅ Dispatcher initialized with 2 handlers
🚀 Bot @YourGitBot started, listening for commands...
🚀 Server started on port 8080 (version v0.0.1)
Send these commands to your bot in Telegram:
/configure
This will:
- Save your chat in the database
- Create 4 forum topics (Stars, Pushes, Pull Requests, Issues)
- Map each event type to its topic
/connect https://github.com/your-username/your-repo
The bot will respond with:
- Webhook URL
- Content type
- Setup instructions for GitHub/GitLab
GitHub:
- Go to your repository → Settings → Webhooks → Add webhook
- Payload URL: the URL from
/connectoutput - Content type:
application/json - Events:
Send me everything - Click Add webhook
GitLab:
- Go to your project → Settings → Webhooks
- URL: the URL from
/connectoutput - Trigger: select events (Push, Merge Request, Issues, etc.)
- Click Add webhook
Make a push, create an issue, or star your repository. You should receive a notification in the corresponding forum topic.
| Command | Description |
|---|---|
/start |
Welcome message and getting started |
/help |
List of available commands |
/configure |
Set up forum topics for notifications |
/connect <repo_url> |
Connect a GitHub/GitLab repository |
/status |
Show database contents (chats, topics, repos) |
/lang ru or /lang en |
Change notification language |
/version |
Show bot version |
- GitHub webhooks: push, star
- GitLab webhooks: in development
- Auto-detect platform: single webhook endpoint for both GitHub and GitLab
- Long Polling: bot listens for commands like
/start,/help,/connect - Proxy support: works behind HTTP or SOCKS5 proxies (useful in restricted networks)
- i18n: Russian and English (easy to add more)
- Cross-platform: Linux, macOS, Windows, FreeBSD — single binary, no dependencies
- SQLite database: stores chats, topics, repos, event mappings
- MIT licensed: free for any use
| Variable | Required | Default | Description |
|---|---|---|---|
BOT_TOKEN |
Yes | — | Telegram bot token from @BotFather |
TELEGRAM_BOT_USERNAME |
Yes | — | Bot username without @ (e.g., YourGitBot) |
CHAT_ID |
Yes | — | Telegram chat ID for notifications |
SERVER_ADDRESS |
No | 0.0.0.0 |
Listen address (0.0.0.0 = all, 127.0.0.1 = localhost) |
SERVER_PORT |
No | 8080 |
HTTP server port for webhooks |
PROXY_ENABLED |
No | false |
Enable proxy for Telegram API |
PROXY_HOST |
No | — | Proxy host (for restricted networks) |
PROXY_PORT |
No | — | Proxy port |
PROXY_TYPE |
No | HTTP |
Proxy type: HTTP or SOCKS |
DEV_MODE |
No | false |
Enable debug logging |
DOMAIN |
No | — | Public domain/IP for webhook URL generation |
USE_HTTPS |
No | true |
Use https:// in webhook URL |
| Event | Header (X-GitHub-Event) |
Status |
|---|---|---|
| Push | push |
✅ Implemented |
| Star | star |
✅ Implemented |
| Pull Request | pull_request |
⏳ Planned |
| Issues | issues |
⏳ Planned |
| Fork | fork |
⏳ Planned |
| Release | release |
⏳ Planned |
| Workflow Run | workflow_run |
⏳ Planned |
| Event | Header (X-Gitlab-Event) |
Status |
|---|---|---|
| Push Hook | Push Hook |
⏳ Planned |
| Merge Request Hook | Merge Request Hook |
⏳ Planned |
| Issue Hook | Issue Hook |
⏳ Planned |
| Pipeline Hook | Pipeline Hook |
⏳ Planned |
Want more events? Contributions welcome! Adding a new event handler takes ~100 lines of Go — see CONTRIBUTING.md.
The bot uses SQLite (file: data/notifier.db).
| Table | Description |
|---|---|
chats |
Configured Telegram chats |
topics |
Created forum topics |
repos |
Connected repositories |
event_mapping |
Which event goes to which topic |
View data:
- Send
/statusto the bot in Telegram - Or use SQLite CLI:
sqlite3 data/notifier.db "SELECT * FROM chats"
| Problem | Solution |
|---|---|
| "FOREIGN KEY constraint failed" | Run /configure again — chat must be saved before topics |
| Topics not created | Make sure the bot is administrator in the forum group |
| "This chat is not a forum" | Enable Topics in group settings |
| Webhook not receiving events | Check that URL is accessible from internet |
| Notifications go to general chat | Run /configure to create topics and map events |
| "Unknown event: watch" | This is GitHub's watch event — add a handler or ignore |
Wrong IP in /connect output |
Set DOMAIN=your-server.com in .env |
| Bot can't connect to Telegram | Enable proxy: PROXY_ENABLED=true |
- Language: Go 1.21+
- Telegram library: telego — high-performance, fully compliant with Bot API
- Database: SQLite via modernc.org/sqlite — pure Go, no CGO
- Environment: godotenv
- Single binary, no runtime dependencies
- Cross-compilation out of the box
- Fast startup (~10 MB binary, starts in milliseconds)
- Ideal for self-hosted DevOps tools
MIT © marensovich