A Telegram bot that converts Android base ROMs into flashable formats using GitHub Actions as the conversion backend.
- 🤖 Telegram Bot Interface - Simple command-based interaction
- 🔄 Two ROM Types:
- Super ROM - Flashable via fastboot with Windows/Linux flash scripts
- Hybrid ROM - TWRP-flashable with dual A/B slot support
- 📦 Automated Conversion - GitHub Actions handles heavy processing
- ☁️ Cloud Storage - Automatic upload to Google Drive via rclone
- 🏷️ Smart Naming - Auto-extracts ROM metadata (codename-version-romtype.zip)
- ✅ Dual Slot Support - Hybrid ROMs flash to both A and B slots in TWRP
-
Telegram Bot Token
- Create a bot via @BotFather
- Save the token
-
GitHub Repository
- Fork or create a new repository
- Enable GitHub Actions
- Get a Personal Access Token with
repoandworkflowpermissions
-
Google Drive & rclone
- Set up rclone with Google Drive
- Run
rclone configto create a remote (e.g., "gdrive") - Get base64 encoded config:
cat ~/.config/rclone/rclone.conf | base64 -w 0
-
Clone the repository
git clone <your-repo-url> cd rom
-
Install Python dependencies
pip install -r requirements.txt
-
Configure environment variables
cp .env.example .env # Edit .env with your credentials -
Set up GitHub Secrets
Go to your repository settings → Secrets and add:
RCLONE_CONFIG- Base64 encoded rclone configDRIVE_FOLDER_PATH- Google Drive folder path (e.g., "ROM_Builds")RCLONE_REMOTE_NAME- rclone remote name (e.g., "gdrive")
-
Run the bot
python bot.py
/start- Show welcome message and usage instructions/convert <rom_url> <type>- Start ROM conversion<rom_url>- Direct download URL for base ROM<type>- Eithersuperorhybrid
/status <job_id>- Check conversion status
/convert https://example.com/base_rom.zip hybrid
The bot will:
- Trigger GitHub Actions workflow
- Download the ROM
- Extract metadata (codename, version)
- Convert to hybrid format with dual A/B slot support
- Upload to Google Drive with naming:
PKG110-16.0.0.205-hybrid.zip - Send you the download link
- Flashable via fastboot on Windows
- ✓ Includes Android Platform Tools (fastboot.exe) - no separate installation needed!
- Includes:
super.img- Combined system/vendor/product partitionsboot.img,dtbo.img,vbmeta.img- Boot partitionsflash-all.bat- Windows flasher scriptplatform-tools/- Bundled Android tools
Usage:
# Boot device to fastboot mode
# Windows (uses bundled fastboot):
flash-all.bat- Flashable via TWRP recovery
- Automatically flashes to both slot A and slot B
- Ensures both slots have identical ROM installation
- Includes shell-based update-binary for maximum compatibility
Usage:
- Boot to TWRP recovery
- Install the ZIP file
- Both slots A and B will be flashed
- Reboot to system
rom/
├── .github/
│ └── workflows/
│ └── rom-converter.yml # GitHub Actions workflow
├── scripts/
│ ├── convert_to_super.sh # Super ROM converter
│ ├── convert_to_hybrid.sh # Hybrid ROM converter
│ ├── extract_rom_info.py # Metadata extraction
│ └── upload_to_drive.sh # rclone upload script
├── bot.py # Main Telegram bot
├── config.py # Configuration
├── requirements.txt # Python dependencies
├── .env.example # Environment variables template
└── README.md # This file
# Telegram
TELEGRAM_BOT_TOKEN=your_bot_token
# GitHub
GITHUB_TOKEN=your_github_token
GITHUB_REPO_OWNER=your_username
GITHUB_REPO_NAME=rom
# Google Drive
DRIVE_FOLDER_PATH=ROM_Builds
RCLONE_REMOTE_NAME=gdrive
# Optional
MAX_CONCURRENT_JOBS=3| Secret | Description | Example |
|---|---|---|
RCLONE_CONFIG |
Base64 encoded rclone config | W3JlbW90ZV0... |
DRIVE_FOLDER_PATH |
Google Drive folder path | ROM_Builds |
RCLONE_REMOTE_NAME |
rclone remote name | gdrive |
- User sends command → Bot receives ROM URL and type
- Bot triggers GitHub Actions → Repository dispatch event
- GitHub Actions workflow runs:
- Downloads ROM from URL
- Extracts metadata (codename, version)
- Converts to super/hybrid format
- Uploads to Google Drive
- Generates shareable link
- Bot monitors workflow → Polls GitHub API for completion
- Bot sends link → User receives download URL
- Check if bot token is correct
- Ensure bot is running (
python bot.py) - Check logs for errors
- Check GitHub Actions logs
- Verify ROM URL is accessible
- Ensure rclone config is properly base64 encoded
- Verify rclone configuration
- Check Google Drive permissions
- Ensure sufficient storage space
- Super ROM: Ensure device is in fastboot mode and bootloader is unlocked
- Hybrid ROM: Use TWRP recovery compatible with your device
- lpunpack/lpmake - For super partition handling
- rclone - For Google Drive integration
- python-telegram-bot - For Telegram bot framework
MIT License - Feel free to modify and distribute
For issues or questions, please open an issue on GitHub.