核心能力验证

技术研究人工智能 Telegram

GitHub Actions 提供了多种事件触发机制，其中与外部集成相关的包括：

GitHub Actions 触发机制分析

可用的触发器类型

GitHub Actions 提供了多种事件触发机制，其中与外部集成相关的包括：

触发器	用途	外部调用可行性
`push`	代码推送	❌ 不可控
`schedule`	定时触发	❌ 固定时间
`workflow_dispatch`	手动触发	✅ REST API 支持
`repository_dispatch`	通用 Webhook	✅ REST API 支持

workflow_dispatch 详解

这是最适合本场景的触发器。它允许通过 GitHub REST API 手动触发工作流，并支持传入输入参数：

on:
  workflow_dispatch:
    inputs:
      command:
        description: 'Command to execute'
        required: true
        type: choice
        options:
          - deploy
          - build
          - test
      environment:
        description: 'Target environment'
        required: true
        type: string

调用方式：

curl -X POST \
  -H "Authorization: Bearer $GITHUB_TOKEN" \
  -H "Accept: application/vnd.github+json" \
  https://api.github.com/repos/OWNER/REPO/actions/workflows/WORKFLOW_ID/dispatches \
  -d '{"ref":"main","inputs":{"command":"deploy","environment":"production"}}'

关键约束：

需要具有 repo 或 actions:write 权限的 GitHub Token
每分钟 API 调用次数限制（默认 1000 次/小时）
工作流文件必须存在于默认分支

repository_dispatch 备选

如果需要更灵活的触发方式（不绑定特定工作流文件），可以使用 repository_dispatch：

on:
  repository_dispatch:
    types: [telegram-command]

这种方式可以携带自定义 client_payload，适合复杂参数传递。

权限与安全

GitHub Token 需要以下权限：

actions:write - 触发工作流
contents:read - 读取工作流文件（用于验证）

建议使用 Fine-grained Personal Access Token（细粒度令牌），限制只能访问特定仓库。

Telegram Bot API 能力分析

Webhook vs Long Polling

Telegram Bot 接收消息有两种方式：

特性	Webhook	Long Polling
实时性	~50ms	1-2s（轮询间隔）
服务器要求	需要公网 HTTPS	仅需出站连接
扩展性	支持水平扩展	单进程限制
防火墙	需开放 443 入站	仅需出站 443
适用场景	生产环境	开发测试

结论：生产环境必须使用 Webhook。

Slash Commands 配置

Telegram Bot 支持通过 BotFather 配置斜杠命令菜单：

/command1 - Description
/command2 - Description

配置命令后，用户在输入 / 时会看到自动补全菜单，提升用户体验。

Webhook 设置要求

根据官方文档，Webhook 设置有以下硬性要求：

仅支持端口：80, 88, 443, 8443
必须使用有效 TLS 证书（自签名证书需额外配置）
响应时间必须在 60 秒内
返回 HTTP 200 确认接收成功

# 设置 Webhook
curl -X POST "https://api.telegram.org/bot<TOKEN>/setWebhook" \
  -d "url=https://your-domain.com/webhook" \
  -d "secret_token=YOUR_SECRET"

# 验证 Webhook 状态
curl "https://api.telegram.org/bot<TOKEN>/getWebhookInfo"

现有解决方案调研

GitHub Actions 生态

市场上有多个成熟的 Telegram 通知 Actions：

cbrgm/telegram-github-action (19 stars)
- 功能：从 Actions 发送消息到 Telegram
- 局限：单向通信（Actions → Telegram）
an3park/telegram-action (6 stars)
- 功能：支持 Markdown/HTML 格式化、文件发送
- 局限：单向通信
appleboy/telegram-action (500+ stars，最流行)
- 功能：通知工作流状态（成功/失败）
- 局限：单向通信

关键发现：所有现有 Actions 都只解决 Actions → Telegram 的单向通知问题，没有解决 Telegram → Actions 的反向触发问题。

集成平台方案

Pipedream 提供了现成的集成方案：

支持 “Telegram Bot Command Received” 触发器
支持 “GitHub Create Workflow Dispatch” 动作
免费额度：每月 10,000 次调用（足够小规模使用）

这是最快实现路径，适合概念验证和小型项目。

能力缺口总结

GitHub Actions 端

✅ 支持：通过 REST API 接受外部触发
❌ 不支持：原生监听 Telegram Webhook
⚠️ 限制：需要有效的 GitHub Token 和 API 调用权限

Telegram Bot 端

✅ 支持：Webhook 接收消息、Slash Commands 菜单
✅ 支持：通过 Bot API 发送消息（双向通信的基础）
❌ 不支持：直接调用外部 API（需要中间服务）

必须构建的组件

实现双向集成，必须自行构建：

Webhook 接收服务：接收 Telegram 消息
命令解析逻辑：提取命令和参数
GitHub API 调用：触发 Actions
结果反馈：将执行状态发送回 Telegram

验证结论

技术可行性：✅ 可行

GitHub Actions 和 Telegram Bot API 都提供了足够的接口支持此集成。核心方案是：

Telegram Webhook → 中间服务
中间服务 → GitHub REST API
Actions 执行 → 结果回调 → Telegram

需要关注的边界条件：

GitHub API 速率限制（建议增加缓存和限流）
Webhook 安全性验证（使用 secret_token）
错误处理和重试机制

参考资料

GitHub REST API - Workflow Dispatch - GitHub 官方 API 文档
Telegram Bot API Documentation - Telegram 官方文档
cbrgm/telegram-github-action - 流行的 Telegram Actions 插件
Pipedream - Telegram to GitHub Integration - 低代码集成方案