🚀 CommitCaster

Transform your GitHub commits into engaging Telegram posts with AI

✨ Features

• 🤖 AI-Powered Posts - Generate engaging commit descriptions using Groq's free LLM API
• 📱 Telegram Integration - Automatic publishing to your Telegram channel
• 🔔 Real-time Webhooks - Instant notifications on every push event
• 🐳 Docker Ready - Deploy in 5 minutes with Docker Compose
• 🔒 SSL/HTTPS - Automatic certificate setup with Let's Encrypt
• 💰 100% Free - Uses free Groq API (llama-3.3-70b-versatile)
• 🌍 Multi-mode - Single-user or SaaS multi-tenant deployment

🎯 How It Works

┌─────────────┐       ┌─────────────┐       ┌─────────────┐       ┌─────────────┐
│   GitHub    │──────▶│ CommitCaster│──────▶│   Groq AI   │──────▶│  Telegram   │
│   Push      │webhook│    Server   │ API   │  Generate   │ API   │   Channel   │
└─────────────┘       └─────────────┘       └─────────────┘       └─────────────┘

1. You push code to your GitHub repository
2. GitHub sends a webhook to your CommitCaster server
3. CommitCaster analyzes the commit and sends it to Groq AI
4. AI generates an engaging post
5. Post is automatically published to your Telegram channel

🚀 Quick Start (5 minutes)

Prerequisites

• VPS server (Ubuntu/Debian) or local machine with Docker
• Domain name (for production with HTTPS)
• Telegram bot and channel
• Groq API key (free)

Installation on VPS

# 1. Clone the repository
git clone https://github.com/Minkaill/commit-caster-bot.git
cd commit-caster-bot

# 2. Create .env file
nano .env

Add your configuration:

TELEGRAM_BOT_TOKEN=your_bot_token_from_BotFather
TELEGRAM_CHANNEL_ID=@yourchannel
GROQ_API_KEY=your_groq_api_key
GITHUB_WEBHOOK_SECRET=your_secret_key
PORT=8080

# 3. Install Docker
apt install -y docker.io docker-compose

# 4. Start the bot
docker-compose -f docker-compose.single.yml up -d --build

# 5. (Optional) Setup Nginx + SSL
apt install -y nginx certbot python3-certbot-nginx
# Follow instructions in DEPLOYMENT.md

Done! Bot is now running at http://your-server:8080

Local Development

# 1. Install dependencies
go mod download

# 2. Create .env file (see above)

# 3. Run
go run cmd/bot/main.go

# 4. Use ngrok for HTTPS URL (required by GitHub)
ngrok http 8080

📋 Getting API Keys

1. Telegram Bot Token

1. Open @BotFather in Telegram
2. Send /newbot
3. Follow the instructions
4. Copy the token

2. Telegram Channel ID

1. Create a public Telegram channel
2. Add your bot as an administrator with post permissions
3. Use @yourchannel or numeric ID

3. Groq API Key (FREE! 🎉)

1. Visit console.groq.com
2. Sign up (Google OAuth available)
3. Go to API Keys → Create API Key
4. Copy the key

4. GitHub Webhook Secret

Generate a random secret:

openssl rand -hex 32

⚙️ GitHub Webhook Setup

1. Open your GitHub repository
2. Go to Settings → Webhooks → Add webhook
3. Fill in:
   • Payload URL: https://your-domain.com/webhook/github
   • Content type: application/json
   • Secret: your GITHUB_WEBHOOK_SECRET
   • Events: Just the push event
4. Click Add webhook

🐳 Docker Commands

# Start
docker-compose -f docker-compose.single.yml up -d --build

# View logs
docker-compose -f docker-compose.single.yml logs -f

# Restart
docker-compose -f docker-compose.single.yml restart

# Stop
docker-compose -f docker-compose.single.yml down

# Check status
docker-compose -f docker-compose.single.yml ps

Or use the Makefile:

make docker-up      # Start the bot
make logs           # View logs
make docker-restart # Restart
make health         # Check health
make update         # Update the bot

📁 Project Structure

CommitCaster/
├── cmd/
│   └── bot/
│       └── main.go              # Entry point
├── config/
│   └── config.go                # Configuration
├── internal/
│   ├── handlers/
│   │   └── webhook.go           # GitHub webhook handler
│   ├── models/
│   │   └── github.go            # Data models
│   ├── services/
│   │   ├── ai.go                # Groq AI service
│   │   └── telegram.go          # Telegram API
│   └── database/                # Database (SaaS mode)
├── docs/                        # Swagger documentation
├── docker-compose.single.yml    # Single-user Docker setup
├── docker-compose.yml           # Multi-user Docker setup
├── deploy.sh                    # Automatic VPS deployment
├── update.sh                    # Update script
├── Dockerfile                   # Multi-stage Docker build
├── Makefile                     # Convenient commands
├── .env.example                 # Configuration example
└── README.md

🎨 Customization

Change Post Style

Edit the prompt in internal/services/ai.go:

prompt := `You are an experienced developer. Write a short post for a Telegram channel...`

Change AI Model

In internal/services/ai.go, modify the model:

"model": "llama-3.3-70b-versatile", // or llama-3.1-70b, mixtral-8x7b

All models are free on Groq!

Limit Commits Per Post

In internal/handlers/webhook.go:102, change the limit:

if i >= 5 { // Limit to 5 commits

📖 Documentation

• VPS_QUICKSTART.md - Quick deployment in 5 minutes
• DEPLOYMENT.md - Detailed deployment guide
• API.md - API documentation
• Swagger UI - Interactive API docs

🔧 Troubleshooting

Error: "Invalid signature"

Check that GITHUB_WEBHOOK_SECRET in .env matches the secret in GitHub webhook settings.

Error: "telegram API error"

• Ensure the bot is added as an administrator to the channel
• Verify TELEGRAM_CHANNEL_ID is correct (should start with @)

AI not responding

• Verify GROQ_API_KEY is correct
• Check your quota at console.groq.com

Webhook not working

1. Check Recent Deliveries in GitHub webhook settings
2. View logs: docker-compose -f docker-compose.single.yml logs
3. Ensure domain is accessible: curl https://your-domain.com/health

🌟 Use Cases

Personal Dev Blog

Share every commit to your Telegram channel with beautiful AI-generated descriptions.

Team DevBlog

Keep your team informed about new features and fixes automatically.

Open Source Updates

Keep your community updated on development in real-time.

💰 Cost Breakdown

• VPS: from $5/month (Digital Ocean, Vultr, Hetzner)
• Domain: from $10/year (Namecheap, Cloudflare)
• Groq API: FREE! ✨
• Telegram: free
• GitHub: free
• SSL (Let's Encrypt): free

Total: ~$5-10/month

🚀 Production Deployment

Automated Deployment Script

# One-command deployment
chmod +x deploy.sh
./deploy.sh

The script will:

• Install Docker, Nginx, Certbot
• Create .env configuration
• Setup Nginx reverse proxy
• Install SSL certificate
• Start the bot

Manual Deployment

See DEPLOYMENT.md for step-by-step instructions.

🔐 Security

• Webhook signature verification (HMAC-SHA256)
• SSL/TLS encryption
• Environment variable isolation
• Docker container sandboxing

📊 Performance

CommitCaster is extremely lightweight:

• RAM: ~20-50MB
• CPU: <1% at idle
• Disk: ~50MB (Docker image)

A single cheap VPS can handle thousands of webhooks per day.

🤝 Contributing

Pull requests are welcome! For major changes, please open an issue first.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/AmazingFeature)
3. Commit your changes (git commit -m 'Add some AmazingFeature')
4. Push to the branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

📝 License

MIT

🙏 Acknowledgments

• Built with Groq for blazing-fast AI inference
• Powered by Gin web framework
• Created with Claude Code

📞 Support

• 🐛 Found a bug? Create an issue
• 💬 Have questions? Start a discussion
• ⭐ Like the project? Give it a star!

---

Made with ❤️ by developers, for developers