README

此包提供了将 Telegram 消息服务和 GitHub/GitLab 集成的功能。使用此包，您可以创建一个 Telegram 机器人来接收 GitHub 或 GitLab 事件的推送通知，并通过 Telegram 的消息和按钮进行自定义管理。

📝 信息

• 将 GitHub/GitLab 仓库的通知发送到 Telegram 机器人、群组、超级群组（多主题）和频道。
• 机器人必须使用 BotFather 创建。

🎉 特性

1. GitHub/GitLab 通知到 Telegram：此包允许您配置一个 Telegram 机器人来接收来自各种 GitHub/GitLab 事件的推送通知，包括提交、拉取请求、问题、发布等事件。

1. 自定义通知：您可以通过 Telegram 的选项自定义想要接收的通知类型。

1. 交互式按钮：该包支持在 Telegram 上创建交互式按钮，以执行启用或禁用通知等操作。

1. 事件管理：您可以管理想要接收推送通知的特定事件，从而集中精力关注项目中最重要的事情。

   • 支持多个平台：GitHub 和 GitLab。
   • 在不同平台之间分别管理事件通知。

1. 易于集成：该包提供 API 和用户友好的功能来创建 Telegram 机器人并将其链接到您的 GitHub/GitLab 账户。

1. 支持多个聊天：您可以将多个聊天 ID 添加到 .env 文件中。这些聊天 ID 将是您的群组、频道或用户的聊天 ID。您还可以添加 该机器人的聊天 ID 以接收来自自己的推送通知。

1. 对于付费用户，您可以使用以下功能
   • 支持多个主题：您可以将多个主题添加到 .env 文件中。这些主题将是您的超级群组的话题。

📋 要求

• PHP ^8.1
• Composer
• 核心：Telegram Git Notifier

🔧 安装

关于安装和配置，该项目提供了两种不同的安装方式，具体取决于您的偏好或系统兼容性。

方式 1：通过 composer 直接在系统上安装（需要系统已安装 composer，之前的 PHP 版本）

方式 2：通过 Docker 安装（需要系统已安装 Docker 和 Docker Compose）

I. 安装和配置 🛠

请仅选择以下两种方式之一来设置项目。

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. 设置 webhook

我们有两种设置 webhook 的方法

1. 从此项目设置 webhook

在设置好域名和SSL证书后，您需要为您的小助手设置webhook。

前往

<APP_URL>/webhooks/set.php

注意：将 <APP_URL> 替换为.env文件中的您的应用URL。

如果您看到以下消息，则表示webhook已成功发送。

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

2. 从Telegram手动设置webhook

如果您想手动设置webhook，可以使用以下URL

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

注意：将 <YourTelegramBotToken> 替换为您的bot令牌，将 <APP_URL> 替换为.env文件中的您的应用URL。

III. 将您想要接收通知的聊天ID添加到.env文件中

1. 将多个聊天ID添加到.env文件中。

这些聊天ID将是您的群组、频道或用户的聊天ID。

此外，您还可以添加 该小助手的聊天ID 以接收针对自身的传入通知。

TELEGRAM_NOTIFY_CHAT_IDS="-978339113;-1001933979183"

2. 为有高级用户的超级群组添加主题（Thread ID）

您可以为有高级用户的超级群组添加主题（Thread ID）。

这些主题将是您的超级群组主题。

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

3. 为有高级用户的超级群组添加多个主题（Thread IDs）

您可以为每个有高级用户的超级群组添加多个主题（Thread IDs）。

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

注意

• 请使用分号 ";" 分隔聊天ID
  • 使用冒号 ":" 分隔聊天ID和主题
  • 如果您想添加多个主题，则使用逗号 ","

现在您的配置已完成。并且.env文件将如下所示

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

🚀 使用方法

现在您可以向小助手发送消息，您将收到小助手的欢迎消息。

/start

如果您想检查菜单，可以向小助手发送以下消息。

/menu

🎊 到此为止，您的Telegram小助手的配置过程已完成。您可以使用该小助手的全部功能。 🎉🎉

为了提高易用性。让我们为您创建一个包含命令列表的菜单。

请向小助手发送以下消息以创建菜单按钮。

/set_menu

现在您需要添加GitHub和GitLab仓库的Webhook以接收通知。

📌 在GitHub仓库上添加Webhook以接收通知

1. 进入您的仓库设置。
2. 进入Webhooks部分。
3. 点击添加webhook。
4. 将Payload URL设置为<APP_URL>。
5. 将Content type设置为application/x-www-form-urlencoded。
6. 您想触发哪些事件？选择让我选择个别事件。。
7. 点击Active复选框和添加webhook按钮。
8. 完成。当您的仓库有新事件时，您将收到通知。

以下是您将收到的第一个通知

📌 在GitLab仓库上添加Webhook以接收通知

1. 进入您的仓库设置。
2. 进入Webhooks部分。
3. 点击添加新webhook。
4. 将URL设置为<APP_URL>。
5. 选择您想要的任何触发器。
6. 点击启用SSL验证复选框和添加webhook按钮。

注意：您可以为此设置不同的webhook。请为每个仓库类似地设置webhook。

然后，每当这些仓库出现事件时，这个Telegram小助手将立即向您发送通知。