TB GitHub Release

Service that monitors GitHub repositories for new releases and sends Telegram notifications when one is published.

Features

• Scheduled checks — Cron-based verification (configurable)
• SQLite storage — Tracks last known release per repo
• Telegram notifications — Rich HTML messages with release notes, author, links
• Retry logic — Automatic retries for GitHub API and Telegram on failure
• Health endpoint — GET /health for Docker/orchestration
• Prereleases excluded — Only stable releases are notified

Requirements

• Bun v1.x
• GitHub token (required)
• Telegram bot token

Environment Variables

Variable	Required	Description
TELEGRAM_BOT_TOKEN	Yes	Bot token from @BotFather
TELEGRAM_CHAT_ID	Yes	Numeric chat/channel ID to receive notifications
GITHUB_TOKEN	Yes	Personal access token (create). Min 10 chars. Required for API rate limits.
GITHUB_REPO	Yes	Comma-separated list of repos (owner/repo1,owner/repo2)
SCHEDULE	Yes	Cron expression (e.g. 0 0 * * * = daily at midnight)
DATABASE_URL	No	SQLite path (default: ./data/releases.db)
HEALTH_PORT	No	Port for health endpoint (default: 8080)

Getting TELEGRAM_CHAT_ID

1. Start a chat with your bot
2. Send a message
3. Visit https://api.telegram.org/bot<TOKEN>/getUpdates
4. Find chat.id in the response

Quick Start

cp .env.example .env
# Edit .env with your values

bun install
bun run start

Commands

Command	Description
bun run start	Start the server (cron + health endpoint)
bun run dev	Start with watch mode
bun run check	Run a single manual check and exit
bun run test:notify	Send a test notification (fake data)
bun run test:notify:db [repo]	Send a test notification from DB (e.g. stalwartlabs/stalwart)

Docker

docker compose up -d

• Builds from Dockerfile (Bun Alpine)
• Uses .env for configuration
• Health check every 30s on port 8080

Database storage

The SQLite database is stored in /app/data/releases.db inside the container. You can persist it in two ways:

Option 1: Named volume (default)

The default docker-compose.yml uses a named volume releases_data. Data survives docker compose down but not docker compose down -v.

volumes:
  - releases_data:/app/data

Option 2: Bind mount (host directory)

Mount a host directory to access or backup the database directly:

volumes:
  - ./data:/app/data

Create the directory first: mkdir -p data. The database file will be at ./data/releases.db on your host.

Project Structure

src/
├── config/       # Env validation & config
├── services/     # GitHub, Telegram, DB, release checker
├── scripts/      # CLI scripts (check, test-notify)
├── utils/        # Retry helper
└── index.ts      # Entry point

License

MIT