GitHub Telegram Notification Bot

Telegram-бот для получения уведомлений о событиях в репозиториях GitHub с фильтрацией.

🚀 Особенности

• Фильтрация - по типам событий, авторам, репозиториям
• Группировка событий - получайте события отдельно или все разом
• Поддержка приватных репозиториев - через GitHub token

Поддерживаемые события

• 📤 Push - коммиты с авторами и ссылками на diff
• 📝 Issues - создание, закрытие, комментарии
• 🔀 Pull Requests - создание, merge, комментарии к коду
• ⚙️ GitHub Actions - статус workflow (успех/ошибка)

📋 Требования

• Python 3.10+
• Redis сервер
• GitHub Personal Access Token (read:repo)
• Telegram Bot Token

🛠 Установка и запуск

Вариант 1: Docker (рекомендуется)

# 1. Клонируйте репозиторий
git clone https://github.com/yourusername/gh_notification_bot.git
cd gh_notification_bot

# 2. Настройте .env
cp .env.example .env
nano .env

# 3. Запустите
docker-compose up -d

# 4. Проверьте логи
docker-compose logs -f bot

Вариант 2: Локально

# 1. Установите зависимости
pip install -r src/requirements.txt

# 2. Запустите Redis
redis-server

# 3. Настройте .env
cp .env.example .env
nano .env

# 4. Запустите бота
python src/main.py

⚙️ Конфигурация (.env)

# Telegram Bot (@BotFather)
TELEGRAM_BOT_TOKEN=ваш токен

# GitHub Token (Settings → Developer settings → Personal access tokens)
# Права: repo (для приватных) или public_repo (для публичных)
# Для webhooks добавьте: admin:repo_hook
GITHUB_TOKEN=ghp_xxxxxxxxxxxxxxxxxxxx

# Redis
REDIS_HOST=localhost
REDIS_PORT=6379
REDIS_DB=0
REDIS_PASSWORD=

# Webhooks (обязательно! Бот работает только через webhooks)
# Для локальной разработки используйте ngrok (см. инструкцию ниже)
WEBHOOK_HOST=http://localhost
WEBHOOK_PORT=8080
WEBHOOK_SECRET=change_this_secret

🌐 Настройка Webhooks (обязательно)

Бот работает только через GitHub Webhooks для получения мгновенных уведомлений с полными данными о коммитах.

Настройка ngrok (для локальной разработки)

1. Зарегистрируйтесь на https://dashboard.ngrok.com/signup (бесплатно)
2. Скачайте ngrok с https://ngrok.com/download
3. Распакуйте ZIP в любую папку (например, C:\ngrok)
4. Получите authtoken на https://dashboard.ngrok.com/get-started/your-authtoken
5. Установите authtoken:

cd C:\ngrok
ngrok.exe config add-authtoken YOUR_AUTHTOKEN_HERE

6. Запустите туннель:

ngrok.exe http 8080

Результат:

ngrok

Session Status                online
Forwarding                    https://abc123-def456.ngrok-free.app -> http://localhost:8080

Скопируйте URL (например, https://abc123-def456.ngrok-free.app) для настройки WEBHOOK_HOST

Обновите .env

# Скопируйте URL из ngrok (вместо http://localhost)
WEBHOOK_HOST=https://abc123-def456.ngrok-free.app
WEBHOOK_PORT=8080
WEBHOOK_SECRET=your_secure_secret_key

Пересоберите контейнер

docker-compose down
docker-compose up -d --build

Подпишитесь на репозиторий

Теперь при подписке бот автоматически создаст webhook и вы увидите:

✅ Подписка оформлена!
owner/repo
⭐ 150 stars
🔗 Webhook настроен (мгновенные уведомления)

Что даёт webhooks:

• ✅ Мгновенные уведомления (0 секунд задержки)
• ✅ Полный список коммитов с описаниями и ссылками
• ✅ Минимальная нагрузка на GitHub API

Для продакшена: Вместо ngrok используйте свой публичный домен (VPS, облако, Heroku и т.д.)

📱 Использование

Команды бота

Команда	Описание
📝 Подписаться	Подписаться на репозиторий
📋 Мои подписки	Список активных подписок
⚙️ Фильтры	Настройка фильтров
❌ Отписаться	Отписаться от репозитория
ℹ️ Помощь	Справка по боту

Быстрый старт

1️⃣ Настройте ngrok и WEBHOOK_HOST (см. секцию выше)
2️⃣ Откройте бота - 📝 Подписаться
3️⃣ Отправьте: https://github.com/owner/repo
4️⃣ Готово! Уведомления приходят мгновенно

Настройка фильтров

Фильтры - выберите репозиторий

• Исключить автора - dependabot[bot]
• Типы событий - выбрать нужные
• Группировка - ВКЛ/ВЫКЛ

Группировка событий:

• ВЫКЛ (по умолчанию) - каждое событие отдельным сообщением
• ВКЛ - все события за минуту в одном сообщении

Принцип работы

1. Webhook: GitHub отправляет события на ваш сервер мгновенно
2. Фильтрация: Проверяет настройки для каждого чата
3. Форматирование: Преобразует события в читаемый формат с HTML
4. Отправка: Отправляет уведомления в Telegram