The workflow_run webhook payload carries no jobs array, only jobs_url, so the Jobs field never populated for real GitHub events. Fetch the job list from the GitHub API once per delivery (lazy, memoized across routes) and inject it into the payload before formatting. - app-token.ts: shared getInstallationToken (App JWT -> installation token) + GITHUB_API_VERSION; check-run.ts now reuses it - workflow-jobs.ts: getWorkflowRunJobs, App token when configured else unauthenticated (public repos), per_page=100, best-effort - docs: GitHub App needs Actions: read; note API enrichment in the message-format and supported-events guides (en + zh)
13 KiB
部署
Cloudflare 设置
1. 创建 KV 命名空间
bunx wrangler kv namespace create KV
这会输出一个命名空间 ID。更新 wrangler.jsonc,填入 ID:
{
"kv_namespaces": [
{
"binding": "KV",
"id": "your-namespace-id",
},
],
}
2. 设置密钥
bunx wrangler secret put GITHUB_WEBHOOK_SECRET
bunx wrangler secret put GITHUB_CLIENT_ID
bunx wrangler secret put GITHUB_CLIENT_SECRET
bunx wrangler secret put DISCORD_TOKEN
bunx wrangler secret put DISCORD_PUBLIC_KEY # Discord 应用的公钥(开发者门户获取),交互功能必需
bunx wrangler secret put TELEGRAM_TOKEN # Telegram Bot Token(BotFather 获取)—— Telegram 路由必需
bunx wrangler secret put FEISHU_APP_ID # 飞书应用 ID —— 飞书路由必需
bunx wrangler secret put FEISHU_APP_SECRET # 飞书应用密钥 —— 飞书路由必需
bunx wrangler secret put ADMIN_USER_IDS # 逗号分隔的 GitHub ID/登录名,允许进入 Web UI
::: tip 目标频道按路由配置
不存在全局频道密钥。每条路由在 Web 控制台 中声明各自的目标频道(及可选的子区/thread),因此不需要 DISCORD_CHANNEL_ID。
:::
::: tip GitHub App ID / 私钥为可选
GITHUB_APP_ID + GITHUB_PRIVATE_KEY(PKCS#8 PEM)用于 App 安装流程,在安装后选择页解析安装所属账号的登录名,并用于签发安装令牌做 API 增强——拉取 workflow_run 作业列表与 check-suite 构建日志。可以跳过不设——安装页会显示匿名 inst-{installationId} 分组,公开仓库的作业列表仍会以匿名方式加载,私有仓库的构建日志则省略。OAuth 流程只需要 GITHUB_CLIENT_ID / GITHUB_CLIENT_SECRET。
:::
Discord 交互通过 HTTPS Interactions Endpoint 送达,需要设置 DISCORD_PUBLIC_KEY 并把 Interactions Endpoint URL 指向 https://your-domain/discord/interactions。参见下方 Interactions Endpoint。
3. 创建 D1 数据库并执行迁移
bunx wrangler d1 create webhooker
将返回的数据库 ID 填入 wrangler.jsonc:
{
"d1_databases": [
{
"binding": "DB",
"database_name": "webhooker",
"database_id": "your-database-id",
},
],
}
然后执行迁移:
bun run db:migrate:prod # 将迁移应用到远端 D1 数据库
bun run db:migrate # 将迁移应用到本地(Miniflare)数据库
db:migrate 脚本执行 wrangler d1 migrations apply webhooker(见 package.json),逐一应用 migrations/ 下的 SQL 文件,并在 d1_migrations 表中记录已应用的版本。
::: tip 曾用 d1 execute 迁移过的数据库
如果数据库已有这些表/列(例如之前用 wrangler d1 execute --file 迁移过),可能缺少 d1_migrations 追踪表,db:migrate:prod 会尝试重新执行所有迁移;0002_log_detail.sql 中的 ALTER TABLE ... ADD COLUMN 语句会因列已存在而失败。此时请直接执行文件:
bunx wrangler d1 execute webhooker --remote --file ./migrations/0001_init.sql
bunx wrangler d1 execute webhooker --remote --file ./migrations/0002_log_detail.sql
bunx wrangler d1 execute webhooker --remote --file ./migrations/0003_telegram_links.sql
bunx wrangler d1 execute webhooker --remote --file ./migrations/0004_add_group_id.sql
bunx wrangler d1 execute webhooker --remote --file ./migrations/0005_audit_logs.sql
bunx wrangler d1 execute webhooker --remote --file ./migrations/0006_config_d1.sql
bunx wrangler d1 execute webhooker --remote --file ./migrations/0007_send_logs_index.sql
bunx wrangler d1 execute webhooker --remote --file ./migrations/0008_storage_d1.sql
:::
4. 创建 R2 Bucket(可选)
PAYLOAD 绑定将超大 webhook 负载暂存在 R2(webhooker-payloads)而非 KV。未设置时,超大负载回退到 KV 键 queue:payload:*。布局见存储。
bunx wrangler r2 bucket create webhooker-payloads
bucket 已在 wrangler.jsonc 中声明(r2_buckets),无需修改绑定。
5. 创建队列(可选)
QUEUE 绑定会通过 Cloudflare Queues 投递 webhook(异步分发,带重试退避与死信队列)。跳过此步则保持同步内联分发。
bunx wrangler queues create webhooker-delivery
bunx wrangler queues create webhooker-delivery-dlq
队列已在 wrangler.jsonc 中声明(queues.producers / queues.consumers),无需修改绑定。webhooker-delivery 消费者对可重试失败做指数退避重试(5s/30s/2m/10m),达到 max_retries 后消息进入 webhooker-delivery-dlq 并标记为 dead。
6. 部署
bunx wrangler deploy
Worker 现在可通过 https://webhooker.<your-subdomain>.workers.dev 访问。
7. 配置 GitHub Webhook
- 进入 GitHub App 设置页面
- 设置 Webhook URL 为
https://webhooker.<your-subdomain>.workers.dev/webhook - 设置 Webhook secret 与
GITHUB_WEBHOOK_SECRET一致
8.(可选)配置 Gitea Webhook
- 在 Gitea 仓库中进入 设置 → Web 钩子 → 添加 Web 钩子 → Gitea
- 设置 目标 URL 为
https://webhooker.<your-subdomain>.workers.dev/webhook - 设置 HTTP 方法 为
POST、Content Type 为application/json - 设置 密钥 与
GITEA_WEBHOOK_SECRET一致 - 选择要触发的事件(push、议题、拉取请求、发布等)
GitHub App 设置
1. 创建 App
- 打开 https://github.com/settings/apps/new
- 填写:
- GitHub App name:
WebHooker(或自定义名称) - Homepage URL: 你的域名
- Webhook URL:
https://your-domain/webhook - Webhook secret: 生成并复制到
GITHUB_WEBHOOK_SECRET
- GitHub App name:
- 设置权限:
- Repository permissions: Contents (read)、Issues (write)、Pull requests (write)、Metadata (read)、Checks (read)、Actions (read)、Deployments (read)、Discussions (read)、Code scanning alerts (read)、Dependabot alerts (read)
- Organization permissions: Members (read) —— 如果需要
- 订阅事件(全部 28 种支持的事件):
- Push、Pull request、Issues、Issue comment、Workflow run、Workflow job、Status、Deployment、Deployment status、Ping、Release、Create、Delete、Star、Fork、Check run、Check suite、Pull request review、Pull request review comment、Commit comment、Member、Label、Milestone、Discussion、Discussion comment、Repository、Code scanning alert、Dependabot alert
- 生成私钥 — 可选;设置
GITHUB_APP_ID+GITHUB_PRIVATE_KEY后,安装后页面会显示安装所属账号的登录名,并以安装令牌鉴权私有仓库的 API 增强(作业列表、构建日志)(见上方提示)。
2. 安装 App
- 创建后,进入 App 设置页面
- 点击 "Install App" → 选择组织/用户
- 选择要监控的仓库
3. 配置 OAuth
- 进入 App → OAuth 设置
- 设置 Callback URL:
https://your-domain/auth/github/callback - 将 Client ID 和 Client Secret 复制到环境变量
Discord Bot 设置
-
创建新应用 → 进入 Bot 部分
-
将 Bot Token 复制到
DISCORD_TOKEN -
使用
bot与applications.commands两个 scope 邀请 Bot,并勾选View Channels+Send Messages+Send Messages in Threads权限(组合整数274877910016):https://discord.com/oauth2/authorize?client_id=YOUR_BOT_CLIENT_ID&permissions=274877910016&scope=bot+applications.commands -
在 Web UI(
/admin)中按路由配置目标频道——无需全局频道 ID。
Interactions Endpoint
消息通过 Discord REST API 发送,因此仅凭 DISCORD_TOKEN 即可推送。交互(斜杠命令、按钮、modal)则通过 HTTPS Interactions Endpoint 送达:
- 在 Discord 开发者门户 → General Information 复制应用的 Public Key,填入
DISCORD_PUBLIC_KEY。 - 将 Interactions Endpoint URL 设为
https://your-domain/discord/interactions。 - 所有交互请求都使用 Ed25519 签名验证(
X-Signature-Ed25519覆盖X-Signature-Timestamp + body)。
/gh 斜杠命令与 GitHub: 添加/编辑/删除评论 消息命令由定时任务(每 5 分钟)同步注册:按服务器即时可用,同时全局注册(24h 去重,约 1 小时传播)。Bot 从不连接 Discord Gateway,因此显示为离线——消息推送不受影响(始终走 REST)。
用户运行 /gh login 绑定自己的 GitHub 账号,即可以本人身份评论 issue/PR。完整命令说明见机器人命令。
Telegram 机器人配置
- 用 @BotFather 创建机器人,将 Token 复制到
TELEGRAM_TOKEN。 - (可选)设置
TELEGRAM_WEBHOOK_SECRET;webhook 注册时会作为secret_token传给 Telegram,POST /telegram/webhook使用时间安全比较校验。 - Worker 会在定时任务中自动同步 webhook(
setWebhook指向{BASE_URL}/telegram/webhook),因此无需手动调用setWebhook——只需确保BASE_URL已设置。 - 将机器人加入群组(或启用话题),在路由配置中用
chatId/topicId指定目标。
在 Telegram 中,/gh 命令(/gh login、/gh logout、/gh comment <内容>、/gh merge、/gh close)通过在通知消息上回复来使用——见机器人命令。
头像使用内置 GET /api/richheader 渲染为链接预览卡片(可用 TELEGRAM_RICH_HEADER_HOST 覆盖)。
飞书机器人配置
- 进入飞书开放平台 → 创建应用 → 选择企业自建应用 → 填写应用名称。
- 在凭证与基础信息中复制 App ID 与 App Secret,分别填入
FEISHU_APP_ID和FEISHU_APP_SECRET。 - 在权限管理中添加以下任一消息发送权限,用于发送(与读取)消息:
im:message(读取和发送单聊与群聊消息)im:message:send_as_bot(以应用机器人身份发送消息)im:message:send(旧版发送消息权限)
- 在机器人功能中启用机器人。将机器人添加到目标群聊(或创建新群),并在群设置中复制 Chat ID。
- 在 WebHooker
/admin中创建或编辑路由,添加目标:platform: "feishu",chatId填写飞书 Chat ID,子话题可填topicId。
WebHooker 使用应用级凭证(FEISHU_APP_ID / FEISHU_APP_SECRET)请求 tenant_access_token(有效期约 2 小时),缓存到期前复用,并以卡片消息(interactive)形式发送。workflow_run / check_run 的进度更新同样会调用飞书消息编辑接口,原地更新消息。
入站:指令与按钮
与 Discord、Telegram 一样,WebHooker 可接收飞书事件,让用户直接在聊天里操作 PR/Issue:
/gh login—— 绑定 GitHub 账号(打开 OAuth 页面)。/gh logout—— 解绑 GitHub 账号。/gh comment <PR/Issue 链接> <内容>—— 以绑定的 GitHub 身份发表评论。/gh merge <PR 链接>//gh close <PR 链接>—— 以绑定身份合并 / 关闭 PR。- 卡片上的 合并 / 关闭 按钮触发相同操作。
开启入站:
- 在应用的事件订阅中,把请求地址设为
https://<你的-worker>/feishu/webhook(飞书会发送url_verification校验,WebHooker 自动应答)。 - 订阅以下事件:
im.message.receive_v1—— 接收/gh指令(依赖im:message权限)。card.action.trigger—— 接收卡片按钮点击。
- 凭证与基础信息中的 App Secret(即
FEISHU_APP_SECRET)同时用于对入站回调做X-Lark-Signature签名,WebHooker 会校验它。
所需权限
| 权限 | 用途 |
|---|---|
im:message |
读取和发送单聊与群聊消息。 |
im:message:send_as_bot |
以应用机器人身份发送消息(im:message 的替代)。 |
im:message:send |
旧版发送消息权限(im:message 的替代)。 |
Note
不支持“自定义机器人”的群级 Webhook URL。WebHooker 统一使用应用机器人,以保持与 Discord、Telegram 一致的凭证管理、消息编辑、多群路由与入站指令能力。
自定义域名(可选)
要使用自定义域名替代 *.workers.dev:
- 进入 Cloudflare Worker 设置
- 添加自定义域名或路由
- 更新
BASE_URL以匹配
Note
本项目是一个 Cloudflare Worker,依赖
wrangler.jsonc中声明的 KV 与 D1 绑定,无法作为独立的 Node/容器进程运行。Queues 绑定(QUEUE)可选——未绑定时 webhook 分发保持内联同步。