A robust Telegram bot that integrates with GitHub to send real-time event notifications, manage repositories, and interact with issues, pull requests, actions, releases, and discussions directly from Telegram.
- Real-time Notifications: Receive instant updates for Pushes, Issues, Pull Requests, Reviews, Forks, Stars, GitHub Actions, Discussions, and more.
- Repository Management: Add, remove, star, watch, fork, archive, or list repositories directly from Telegram (
/addrepo,/removerepo,/star,/fork, etc.). - Auto-Discovery: Interactively browse and link repositories accessible via your connected GitHub account.
- Interactive Settings: Configure event notification preferences for each repository using inline menus (
/settingsor/config). - Full GitHub Interaction:
- Reply Comments: Reply directly to a notification message in Telegram to post a comment on GitHub.
- Issues & PRs: Create issues, assign members, label, milestone, lock/unlock, pin/unpin, approve, request changes, or merge PRs directly.
- Actions & CI: Monitor workflow runs, dispatch manual workflow runs, rerun failed jobs, cancel runs, and access job logs.
- Releases & Changelogs: View latest releases, draft new releases, and automatically generate changelogs/release notes.
- Discussions: Create new discussions and mark comments as answers directly from Telegram.
- Search: Search issues, pull requests, and repository code seamlessly.
- Privacy & Security:
- Private chat authentication (
/connect). - AES-GCM encrypted storage of OAuth tokens in MongoDB.
- Role-based access control for administrative commands (
/reload). - Transparent privacy policy (
/privacy).
- Private chat authentication (
- Stateless Webhooks: Efficient webhook routing using encrypted payload tokens in webhook URLs without extra database lookups during incoming requests.
- Code: Push events & Commits
- Issues: Open, close, reopen, label, comment, assign, lock, pin, etc.
- Pull Requests: Open, close, review, approve, request changes, merge, draft status, check runs, etc.
- GitHub Actions: Workflow runs, workflow jobs
- Releases & Discussions: Release creation, discussion posts & answered comments
- Wikis: Gollum events
- Settings: Repository updates
- Deploy Keys & Collaborators: Member changes and access key management
- Forks & Stars: Fork and watch/star events
- Go: v1.23 or higher
- Docker & Docker Compose: For containerized deployment.
- MongoDB: v5.0+ (Provided via Docker Compose or MongoDB Atlas).
- Telegram Bot Token: Created via @BotFather.
- GitHub OAuth App: Configured in GitHub Developer Settings.
- Homepage URL: Your domain/bot URL (e.g.,
https://your-domain.com). - Authorization callback URL:
https://your-domain.com/oauth/callback.
- Homepage URL: Your domain/bot URL (e.g.,
Copy sample.env to .env and fill in the required variables:
# --- Telegram ---# Your Telegram Bot Token from @BotFatherTELEGRAM_TOKEN=123456:ABC-DEF...# Public URL where the bot server is reachableTELEGRAM_WEBHOOK_URL=https://your-domain.com# --- GitHub OAuth ---# From your GitHub OAuth App settingsGITHUB_CLIENT_ID=Iv1...GITHUB_CLIENT_SECRET=0123...# --- Webhooks ---# Shared secret for validating GitHub webhook payloads (e.g. openssl rand -hex 16)GITHUB_WEBHOOK_SECRET=your_webhook_secret_here# --- Database ---MONGODB_URI=mongodb://mongo:27017DATABASE_NAME=github_bot# --- Security ---# 32-byte (64 hex characters) string for AES-GCM encryption of stored tokens.# Generate with: openssl rand -hex 32ENCRYPTION_KEY=a1b2c3d4...# --- Server ---PORT=8080# --- Owner / Admin ---# Telegram User ID of the ownerOWNER_ID=123456789Clone the repository:
git clone https://github.com/AshokShau/GithubBot.git cd GithubBotConfigure environment:
cp sample.env .env # Edit .env with your credentialsStart the services:
docker-compose up -d --build
Verify installation: The bot web server runs on
http://localhost:8080. GitHub webhooks are received athttps://your-domain.com/webhook/....
- Install Go dependencies:
go mod download
- Build the binary:
go build -o bot main.go
- Run the application:
./bot
- Start the Bot: Send
/startin Telegram. - Connect GitHub: Send
/connect(in a private chat) to authenticate with your GitHub account via OAuth. - Add Repositories:
- In a group/channel:
/addrepo owner/repo(or alias/add owner/repo). - Or send
/addrepowithout arguments to select interactively from your accessible GitHub repositories.
- In a group/channel:
- Manage Notifications:
- Send
/settings(or alias/config) to view linked repositories and toggle event notifications using inline menus.
- Send
- Interact via Telegram:
- Reply to Notifications: Simply reply to any issue or PR notification message to post a comment on GitHub.
- Execute Quick Actions: Reply with commands like
/close,/reopen,/approve, or/mergeto update GitHub state immediately.
/connect- Connect your GitHub account via OAuth (Private chat only)./disconnect,/logout- Disconnect your GitHub account./me- Display your connected GitHub account profile details.
/addrepo [owner/repo],/add [owner/repo]- Link a repository to the chat./removerepo [owner/repo],/rm [owner/repo]- Unlink a repository from the chat./repos- List all repositories linked to the current chat./repo [owner/repo]- Show repository summary, statistics, and URL./star- Star the repository./unstar- Remove your star from the repository./watch- Watch the repository./unwatch- Stop watching the repository./fork- Fork the repository to your GitHub account./archive- Archive the repository./unarchive- Unarchive the repository./contributors- List top contributors and commit counts./languages- Show language composition breakdown percentages./branches- List repository branches./branch <branch-name>- Show branch details and latest commit./default <branch-name>- Change repository default branch.
/issue <Title>- Create a new issue (supports multi-line body)./comment <text>- Post a comment on an issue or PR (reply to notification)./close- Close an issue or PR (reply to notification)./reopen- Reopen a closed issue or PR (reply to notification)./assign @username- Assign a user to the issue or PR./assignme- Assign yourself to the issue or PR./unassign @username- Unassign a user./label +<label1> -<label2>- Add or remove labels (e.g./label +bug -help-wanted)./labels- List labels for the issue or repository./milestone <name>- Assign a milestone to an issue or PR./lock- Lock conversation on an issue or PR./unlock- Unlock conversation on an issue or PR./pin- Pin an issue./unpin- Unpin an issue.
/approve- Approve a Pull Request (reply to notification)./requestchanges [text]- Request changes on a Pull Request./merge [squash|rebase|merge]- Merge a Pull Request with specified strategy./draft- Convert a Pull Request to Draft status./ready- Mark a Draft Pull Request as Ready for Review./checks- View CI/CD check runs status for the head commit./files- List changed files and addition/deletion line counts./diff- Display change summary (files changed, additions, deletions)./reviews- List review history and approval status./mergeable- Check if a Pull Request has merge conflicts./request @username- Request a review from a GitHub user.
/commit <SHA>- View details for a specific commit SHA./commits- View recent commit history./compare <branch1> <branch2>- Compare two branches or commits.
/actions- List recent workflow runs and statuses./run <workflow.yml> [branch]- Manually trigger a workflow run./rerun- Rerun a failed workflow run (reply to notification)./cancel- Cancel an active workflow run (reply to notification)./logs- Get a link to workflow run logs.
/release- View details for the latest release./release create <tag>- Create a new release with automatically generated notes./changelog [tag]- Generate release notes / changelog for a tag or next release.
/discussion <Title>- Create a new discussion (supports multi-line body)./answered- Mark a discussion comment as the answer (reply to notification).
/find <keyword>- Search issues within the repository./pr <keyword>- Search pull requests within the repository./search <keyword>- Search repository code.
/mute- Mute notifications for the current forum topic/thread./done- Mark corresponding GitHub notification as done (reply to notification)./read- Mark corresponding GitHub notification as read (reply to notification)./stats- Show repository summary statistics (stars, forks, open issues/PRs, contributors)./activity- Show recent activity stream for the repository.
/settings,/config- Manage event notification preferences for linked repositories./reload- Reload administrator permission cache (Admins only)./privacy- View data privacy policy./help- View complete command list and usage help.
Pull requests are welcome! Please ensure you follow standard Go coding practices, update documentation, and verify tests pass before submitting.
This project is licensed under the MIT License - see the LICENSE file for details.
Maintained by:AshokShau
Telegram:https://t.me/FallenProjects
If you encounter a bug or unexpected behavior, please open an issue on GitHub with detailed reproduction steps and logs.
For general queries, announcements, and support, join our channel on Telegram.
⭐ If this project helps you, consider giving it a star.