GitHub Telegram Bot

Monitor any public GitHub repository via Telegram

Features • Quick Start • Commands • 中文文档

---

Features

• Push Notifications - Receive alerts for new commits
• Release Notifications - Get notified when new versions are published
• Issue Tracking - Monitor issue creation, closure, and reopening
• Pull Request Tracking - Track PR status changes
• Monitor Any Public Repo - No repository admin access required
• Persistent Storage - SQLite database for subscription management
• Proxy Support - HTTP/SOCKS5 proxy for Telegram API (v1.2.0+)
• Timezone Configuration - Customize notification timestamps (v1.2.0+)
• Clean Notification Format - Emoji tags and markdown-stripped content (v1.2.0+)

Project Structure

githubbot/
├── cmd/bot/              # Application entry point
├── internal/
│   ├── config/           # Configuration management
│   ├── github/           # GitHub API, Webhook, and Polling
│   ├── notifier/         # Notification service
│   ├── storage/          # Data persistence
│   └── telegram/         # Telegram Bot handlers
├── pkg/logger/           # Logging utilities
├── configs/              # Configuration files
├── Dockerfile
└── docker-compose.yml

Monitoring Modes

Mode	Description	Use Case
polling (recommended)	Periodically polls GitHub API	Monitor any public repository
webhook	Receives GitHub push events	Only for repos you administer
both	Enables both modes	Mixed scenarios

Note: Polling mode is recommended as it can monitor any public repository without webhook configuration.

Quick Start

Prerequisites

• Go 1.21+
• Telegram Bot Token (from @BotFather)
• GitHub Personal Access Token (optional but strongly recommended)

Installation

1. Clone the repository

   git clone https://github.com/your-username/githubbot.git
   cd githubbot

2. Install dependencies

   go mod download

3. Configure

   cp configs/config.example.yaml configs/config.yaml
   # Edit config.yaml with your settings

4. Run

   go run ./cmd/bot -config configs/config.yaml

Docker Deployment

Using Docker Hub image:

# 1. Pull the image
docker pull gemiluxvii/github-telegram-bot:latest

# 2. Create config file (IMPORTANT: must exist before mounting)
mkdir -p configs data
docker run --rm gemiluxvii/github-telegram-bot:latest \
  cat /app/configs/config.example.yaml > configs/config.yaml

# 3. Edit config.yaml with your tokens
vi configs/config.yaml

# 4. Run the container
docker run -d --name github-bot \
  -v $(pwd)/configs/config.yaml:/app/configs/config.yaml \
  -v $(pwd)/data:/app/data \
  gemiluxvii/github-telegram-bot:latest

Using docker-compose:

mkdir -p configs data
docker run --rm gemiluxvii/github-telegram-bot:latest \
  cat /app/configs/config.example.yaml > configs/config.yaml
vi configs/config.yaml
docker-compose up -d

Configuration

telegram:
  token: "YOUR_BOT_TOKEN"
  debug: false
  proxy: "socks5://127.0.0.1:1080"  # Optional: HTTP/SOCKS5 proxy

github:
  token: "ghp_xxxx"           # Strongly recommended
  mode: "polling"             # polling / webhook / both
  poll_interval: 300          # Seconds

# Timezone for notifications (e.g., "Asia/Shanghai", "America/New_York")
timezone: "UTC"

database:
  path: "./data/bot.db"

server:
  host: "0.0.0.0"
  port: 8080

Proxy Configuration

If you're in a region where Telegram is blocked, configure a proxy:

Proxy Type	Example
HTTP	http://127.0.0.1:7890
SOCKS5	socks5://127.0.0.1:1080
With Auth	socks5://user:pass@127.0.0.1:1080

Timezone Configuration

Common timezone values:

Timezone	Description
UTC	Coordinated Universal Time (default)
Asia/Shanghai	China Standard Time (UTC+8)
Asia/Tokyo	Japan Standard Time (UTC+9)
America/New_York	Eastern Time
Europe/London	British Time

Environment Variables

Format: GHBOT_<SECTION>_<KEY>

export GHBOT_TELEGRAM_TOKEN="your-bot-token"
export GHBOT_GITHUB_TOKEN="ghp_xxxx"
export GHBOT_GITHUB_MODE="polling"

GitHub Token

• Without Token: 60 requests/hour
• With Token: 5000 requests/hour

Get one at: https://github.com/settings/tokens

Bot Commands

Command	Description
/start	Display welcome message
/help	Show help documentation
/subscribe <owner/repo>	Subscribe to a repository
/unsubscribe <owner/repo>	Unsubscribe from a repository
/list	View current subscriptions (with quick unsubscribe buttons)
/status	Show bot status and API quota
/test	Preview all notification formats

Shortcuts: /sub, /unsub

Usage Examples

/subscribe torvalds/linux
/subscribe microsoft/vscode
/subscribe golang/go

License

MIT License