README

Warning

⚠️ This Project is Deprecated – Use the New Laravel Package

• This project is outdated as it is built on a pure PHP source code.
• Instead, we highly recommend using our latest Laravel package, which offers:
  • Better security with built-in authentication and protection mechanisms.
  • More features for modern web development.
  • Active maintenance and community support.
• 👉 Click here to explore the new Laravel Telegram Git Notifier package

Welcome to Telegram Bot GitHub/GitLab Notify 👋

This package provides the ability to integrate the Telegram messaging service and GitHub/GitLab. With this package, you can create a Telegram bot to receive notifications from GitHub or GitLab events and manage customization through messages and buttons on Telegram.

📝 Information

• Send notifications of your GitHub/GitLab repositories to Telegram Bots, Groups, Super Groups (Multiple Topics), and Channels.
• The bot must be created using the BotFather

🎉 Features

1. GitHub/GitLab Notifications to Telegram: The package allows you to configure a Telegram bot to receive notifications from various GitHub/GitLab events, including events like commits, pull requests, issues, releases, and many more.

1. Customize Notifications: You can customize the types of notifications you want to receive through options on Telegram.

1. Interactive Buttons: The package supports creating interactive buttons on Telegram to perform actions such as enabling or disabling notifications.

1. Event Management: You can manage specific events that you want to receive notifications for, allowing you to focus on what's most important for your projects.

   • Support for multiple platforms: GitHub and GitLab.
   • Manage event notifications separately between platforms.

1. Easy Integration: The package provides an API and user-friendly functions to create a Telegram bot and link it to your GitHub/GitLab account.

1. Support for multiple chats: You can add multiple chat IDs to the .env file. These chat IDs will be the chat IDs of your groups, channels, or users. Also, you can add the chat ID of this bot to receive incoming notifications for itself.

1. For premium users, you can use the following features:
   • Support for multiple topics: You can add multiple topics to the .env file. These topics will be the topics of your supergroups.

📋 Requirements

• PHP ^8.1
• Composer
• Core: Telegram Git Notifier

🔧 Installation

As for the installation and configuration, this project provides two different installation ways depending on your preference or suitability for your system.

Way 1: Install by composer directly on the system (Requires the system to install composer, previous PHP version)

Way 2: Install by Docker (Requires the system to install Docker, Docker Compose)

I. Installation and configuration 🛠

Please choose only one of the following two ways to set up the project.

composer create-project cslant/telegram-git-notifier-app

TELEGRAM_BOT_TOKEN=123456789:ABCDEFGHIJKLMNOPQRSTUVWXYZ

TGN_APP_URL=https://123456789.ngrok.io

TELEGRAM_BOT_CHAT_ID=123456789

git clone git@github.com:cslant/telegram-git-notifier-app.git
cd telegram-git-notifier-app
cp .env.example .env

PHP_VERSION_SELECTED=8.2
APP_PORT=3180

# You can customize the container name to suit your needs using GitHub and GitLab
CONTAINER_NAME=tgn-app

bash ./docker.sh

TELEGRAM_BOT_TOKEN=123456789:ABCDEFGHIJKLMNOPQRSTUVWXYZ

ngrok http 172.28.0.3

TGN_APP_URL=https://123456789.ngrok-free.app

TELEGRAM_BOT_CHAT_ID=123456789

II. Set the webhook

We have two ways to set the webhook:

1. Set the webhook from this project

After setting up your domain and SSL certificate, you need to set up the webhook for your bot.

Go to:

<APP_URL>/webhooks/set.php

Note: Replace <APP_URL> with your app URL in .env file.

If you see the following message, it means that the webhook has been sent successfully.

{"ok":true,"result":true,"description":"Webhook was set"}

2. Set the webhook manually from Telegram

If you want to set the webhook manually, you can use the following URL:

https://api.telegram.org/bot<YourTelegramBotToken>/setWebhook?url=<APP_URL>

Note: Replace <YourTelegramBotToken> with your bot token and <APP_URL> with your app URL in the .env file.

III. Add chat IDs you want to receive notifications to the .env file

1. Add multiple chat IDs to the .env file.

These chat IDs will be the chat IDs of your groups, channels, or users.

Also, you can add the chat ID of this bot to receive incoming notifications for itself.

TELEGRAM_NOTIFY_CHAT_IDS="-978339113;-1001933979183"

2. Add a topic for supergroups with premium users (Thread ID)

You can add topic for supergroups with premium users (Thread ID).

These topics will be the topics of your supergroups.

TELEGRAM_NOTIFY_CHAT_IDS="-978339113;-1001933979183:topic_1;"

3. Add multiple topics for supergroups with premium users (Thread IDs)

You can add multiple topics for each supergroup with premium users (Thread IDs).

TELEGRAM_NOTIFY_CHAT_IDS="-978339113;-1001933979183:topic_1,topic_2;"

Note:

• Please use semicolon ";" to separate chat ids
  • And use a colon ":" to separate chat ID and topic
  • And use the comma "," if you want to add multiple topics

Now your configuration is complete. And the .env file will be like this:

TGN_APP_NAME='Telegram GitHub/GitLab Notify Bot'

# Set your app URL here (Required for the bot to work properly)
TGN_APP_URL=https://123456789.ngrok.io

TELEGRAM_BOT_TOKEN=6162840106:AAH3g20lMQIkG_wHHu8R_ngdtG541uzoq4
TELEGRAM_BOT_CHAT_ID=6872320129

# Set the chat IDs that will receive notifications here.
# You can add the owner bot ID, group id, ...
# -------------------------------------------------------
# Note:
# Please use semicolon ";" to separate chat ids
# And use a colon ":" to separate chat ID and thread ID
# And use comma "," if you want to add multiple thread ids
# -------------------------------------------------------
# The environment variable is expected to be in the format:
# "chat_id1;chat_id2:thread_id2;chat_id3:thread_id3_1,thread_id3_2;..."
TELEGRAM_NOTIFY_CHAT_IDS="-978339113;-1001933979183:2,13;6872320129"

TIMEZONE=Asia/Ho_Chi_Minh

PHP_VERSION_SELECTED=8.2
CONTAINER_NAME=tgn-bot
APP_PORT=3180

🚀 Usage

Now you can send a message to your bot, and you will receive a welcome message from the bot.

/start

If you want to check the menu, you can send the following message to your bot.

/menu

🎊 At this point, the configuration process for your telegram bot is completed. You can use all the features of this bot. 🎉🎉

To increase ease of use. Let's create a menu with a list of commands listed for you.

Please send the following message to your bot to create a menu button.

/set_menu

Now you will need to add the Webhook for your GitHub and GitLab repository to receive notifications.

📌 Add webhook on your GitHub repository to receive notifications

1. Go to your repository settings.
2. Go to the Webhooks section.
3. Click on Add webhook.
4. Set Payload URL to <APP_URL>.
5. Set Content type to application/x-www-form-urlencoded.
6. Which events would you like to trigger this webhook? Select Let me select individual events..
7. Click on the Active checkbox and Add webhook button.
8. Done. You will receive a notification when your repository has a new event.

Here is the first notification you will receive:

📌 Add a webhook on your GitLab repository to receive notifications

1. Go to your repository settings.
2. Go to the Webhooks section.
3. Click on Add new webhook.
4. Set URL to <APP_URL>.
5. Choose any Trigger you want.
6. Click on the Enable SSL verification checkbox and Add webhook button.

Note: You can set up this webhook for different repositories. Please similarly set up the webhook for each repository.

Then every time one of those repositories appears an event, this telegram bot will immediately send you a notification.