TensorZero Slack 通知 Worker 完全指南用 Cloudflare Worker 将 GitHub 外部活动实时推送至 Slack【免费下载链接】tensorzeroTensorZero is an open-source LLMOps platform that unifies an LLM gateway, observability, evaluation, optimization, and experimentation.项目地址: https://gitcode.com/GitHub_Trending/te/tensorzero导读本文以 TensorZero 仓库中 ci/slack-notifications-worker/README.md 为核心完整讲解这个 Cloudflare Worker 的职责、部署方式、Secret 配置与 GitHub App 对接细节。它接收 GitHub Webhook 事件将仓库中组织外部成员的新 Issue、新 PR、Review、Discussion 等活动实时推送为 Slack 通知帮助维护者第一时间响应社区贡献。读完本文你将掌握该 Worker 的完整部署与配置流程并能结合 worker.js 的源码理解其签名校验、事件过滤与成员识别等核心实现原理。一、Worker 定位为“外部活动”而生TensorZero 的 CI 目录下维护着一组基于 Cloudflare Workers 的 GitHub 自动化机器人tensorzero-bot-worker 负责 PR 合并队列与冲突标签管理cla-bot-worker 负责 CLA 签名强制而Slack Notifications Worker的职责与众不同——它专注于外部非组织成员活动的通知它是Cloudflare Worker接收 GitHub App 推送的 Webhook 事件处理后调用 Slack API 发送消息所谓“外部活动”指由非tensorzero组织成员通常是社区贡献者发起的 Issue、评论、PR、Review、Discussion 等行为通过wrangler.toml中声明的名称tensorzero-slack-notifications与固定的 Worker URLhttps://tensorzero-slack-notifications.tensorzero.workers.dev对外提供服务。需要特别注意的是README 开篇即强调该 Worker 采用手动部署代码变更不会自动发布。这意味着任何修改都需要显式执行部署命令才会生效这一点在工程流程上需要与 CI 自动部署的组件区分开。二、整体架构与请求处理链路Worker 的入口是fetch处理器worker.js一次完整的通知流程包含六个阶段下面逐一结合源码展开。1. 方法校验仅接受 POSTif (request.method ! POST) { return new Response(Method not allowed, { status: 405 }); }GitHub Webhook 一律以 POST 投递因此 Worker 对非 POST 请求直接返回 405避免健康检查等无关流量进入后续逻辑。2. Webhook 签名校验确保来源可信const signature request.headers.get(X-Hub-Signature-256); if (!signature) { return new Response(Unauthorized, { status: 401 }); } const app createApp(env); const isValid await app.webhooks.verify(body, signature); if (!isValid) { return new Response(Unauthorized, { status: 401 }); }Worker 使用octokit/app的webhooks.verify方法以GITHUB_WEBHOOK_SECRET校验X-Hub-Signature-256请求头。缺失签名或校验失败均返回 401。createAppworker.js同时封装了 GitHub App 的身份凭据function createApp(env) { return new App({ appId: env.GITHUB_APP_ID, privateKey: env.GITHUB_APP_PRIVATE_KEY, webhooks: { secret: env.GITHUB_WEBHOOK_SECRET }, Octokit: MyOctokit, }); }其中MyOctokit是octokit/core与octokit/plugin-rest-endpoint-methods插件组合出的、带 REST 端点方法的客户端实例供后续组织成员查询使用。3. 仓库过滤只处理目标仓库事件if (payload.repository?.full_name ! tensorzero/tensorzero) { return new Response(OK (skipped: wrong repo), { status: 200 }); }即便 GitHub App 被授权接收多个仓库的事件Worker 也会用repository.full_name严格限定只处理tensorzero/tensorzero其余仓库事件静默跳过。这一道防线保证了通知的精准性。4. 事件分发与通知构建buildNotificationworker.js根据X-GitHub-Event请求头分发到对应分支并对 action 做了二次过滤详见下文第四节。无法识别的事件或未匹配的 action 返回nullWorker 直接以OK (skipped)结束。5. 成员识别决定是否真正通知shouldSkipworker.js判定发起者是否为“内部人”是则跳过通知细节见第五节。6. 发送 Slack 消息postToSlackworker.js调用 Slack 的chat.postMessageREST 接口携带 Bot Token 与通知内容见第六节。三、部署与配置从零跑通一个通知机器人部署命令npx wrangler deploy在 ci/slack-notifications-worker 目录下执行即可。依赖项定义在 package.jsonoctokit/app^16.1.2、octokit/core^7.0.6、octokit/plugin-rest-endpoint-methods^17.0.0。Wrangler 配置见 wrangler.tomlname tensorzero-slack-notifications main worker.js compatibility_date 2024-09-23 compatibility_flags [nodejs_compat] [vars] GITHUB_ORG tensorzero SLACK_CHANNEL C09HC3Q2XV2其中nodejs_compat兼容性标志启用 Node.js 兼容 API使octokit等依赖能正常运行GITHUB_ORG与SLACK_CHANNEL作为明文变量写入配置。Secrets五把“钥匙”缺一不可以下 Secret 均通过wrangler secret put NAME设置对应 wrangler.toml 末尾的注释清单Secret 名称用途获取方式GITHUB_APP_IDGitHub App IDGitHub App 设置页面GITHUB_APP_PRIVATE_KEYGitHub App 私钥必须为 PKCS#8 PEM 格式用下面命令转换GITHUB_INSTALLATION_ID安装 IDgh api /orgs/tensorzero/installations --jq .installations[] | \(.app_slug) \(.id)GITHUB_WEBHOOK_SECRETWebhook 密钥与 GitHub App 中配置的值保持一致SLACK_BOT_TOKENSlack Bot 用户 OAuth Token形如xoxb-...其中私钥格式转换命令尤为关键——GitHub 下载的私钥通常是 PEM 格式而octokit/app要求 PKCS#8转换命令为openssl pkcs8 -topk8 -inform PEM -outform PEM -nocrypt -in key.pem -out key-pkcs8.pemGitHub App 配置清单在 GitHub 侧创建/配置应用时需与 Worker 侧严格对齐Webhook URLWorker URLhttps://tensorzero-slack-notifications.tensorzero.workers.devWebhook Secret与GITHUB_WEBHOOK_SECRET相同Repository 权限Issues只读、Pull requests只读、Discussions只读Organization 权限Members只读——这是第五节点成员识别功能所需的权限订阅事件Issues、Issue comments、Pull requests、Pull request reviews、Discussions、Discussion comments。四、六类事件的通知逻辑详解buildNotification的 switch 分支对事件与 action 的组合做了严格限定只在这些精确组合下才产生通知事件X-GitHub-Eventaction 限定通知文案textissuesopenedNew issue opened by loginissue_commentcreatedNew comment on issue by loginpull_requestopenedNew pull request opened by loginpull_request_reviewsubmittedPull request review submitted by logindiscussioncreatedNew discussion created by logindiscussion_commentcreatedNew comment on discussion by login以issues分支为例通知对象同时包含发起者登录名用作actor供后续成员识别与结构化的 Block Kit 消息case issues: if (payload.action ! opened) return null; return { actor: payload.issue.user.login, channel, text: New issue opened by ${payload.issue.user.login}, blocks: formatBlock( New issue opened, payload.issue.title, payload.issue.html_url, payload.issue.user.login, ), };其他分支的模式完全一致仅取用不同的 payload 字段如payload.comment.user.login、payload.review.user.login、payload.discussion.user.login。默认分支返回null即未识别的事件一律静默。五、跳过逻辑如何识别“自己人”shouldSkip是保证“只通知外部活动”的核心采用两级判断async function shouldSkip(actor, env) { if (actor.toLowerCase().endsWith([bot])) return true; try { const app createApp(env); const octokit await app.getInstallationOctokit( Number(env.GITHUB_INSTALLATION_ID), ); await octokit.rest.orgs.checkMembershipForUser({ org: env.GITHUB_ORG, username: actor, }); return true; // 204 is a member } catch (err) { if (err.status 404 || err.status 302) { return false; // not a member } throw err; } }第一级Bot 账号过滤。用户名以[bot]结尾如dependabot[bot]的账号直接跳过——自动化账号的 PR/Issue 无需人工关注。第二级组织成员查询。通过 GitHub App 安装凭证获取getInstallationOctokit调用orgs.checkMembershipForUser查询该用户是否为GITHUB_ORG成员返回 204是成员→ 跳过通知返回404用户不在组织中或 302用户不是该组织成员→ 判定为外部人员放行并通知其他错误认证失败、限流、网络问题一律重新抛出而不是静默放行——这是刻意的设计在不确定用户身份时宁可让通知链路报错失败也不能误发或漏发避免在服务异常期间产生错误的通知语义。六、Slack 消息格式Block Kit 结构化通知通知消息同时包含text纯文本兜底用于不支持 Block 的场景与blocks富文本展示。formatBlockworker.js构造了一个section类型、mrkdwn文本格式的 Blockfunction formatBlock(heading, title, url, actor) { const actorUrl https://github.com/${actor}; return [ { type: section, text: { type: mrkdwn, text: *${heading}*\n\n*Title:* ${url}|${title}\n*Author:* ${actorUrl}|${actor}, }, }, ]; }渲染后的 Slack 消息包含三要素加粗标题如New issue opened、可点击的标题链接指向 Issue/PR/Discussion 页面、作者 GitHub 主页链接。最终投递由postToSlack完成const resp await fetch(https://slack.com/api/chat.postMessage, { method: POST, headers: { Authorization: Bearer ${env.SLACK_BOT_TOKEN}, Content-Type: application/json, }, body: JSON.stringify({ channel: notification.channel, text: notification.text, blocks: notification.blocks, }), }); if (!resp.ok) { throw new Error(Slack API HTTP error: ${resp.status}); } const data await resp.json(); if (!data.ok) { throw new Error(Slack API error: ${data.error}); }注意其双重错误检查既检查 HTTP 状态码resp.ok也检查 Slack API 响应体中的ok字段与error信息——Slack 即使返回 200 也可能在 JSON 中携带业务错误如 Token 失效两层校验确保错误可见、可排查。七、与 TensorZero 其他 Worker 的协作关系该 Worker 并非孤立组件它与 tensorzero-bot-worker/README.md、cla-bot-worker/README.md 共同构成 TensorZero 的 CI 机器人体系三者共享一致的工程约定部署方式一致均为npx wrangler deploy手动部署不随代码提交自动发布Secret 体系高度重叠GITHUB_APP_ID、GITHUB_APP_PRIVATE_KEYPKCS#8 格式、GITHUB_INSTALLATION_ID、GITHUB_WEBHOOK_SECRET是每个 Worker 的公共基础新增机器人时可直接复用分工互补Slack 通知 Worker 面向“外部活动提醒”Bot Worker 面向“PR 合并队列与冲突标签”CLA Bot 面向“贡献者协议签名强制”——分别覆盖社区协作的事前CLA、事中合并管理、事后通知环节。结合 ci/README.md 描述的 GitHub Actions Merge Queue 配置背景可知TensorZero 的 CI 体系对仓库状态检查有精细的编排需求而这组 Worker 正是用无服务器函数在 GitHub 平台能力之外补齐了定制化逻辑。八、排障要点速查收不到通知优先检查签名校验是否通过——GITHUB_WEBHOOK_SECRET必须与 GitHub App 配置一致再检查payload.repository?.full_name是否为tensorzero/tensorzero外部人员未触发通知确认shouldSkip未因 204 误判该用户是否其实已在组织内并确认 GitHub App 已授予Organization → Members只读权限否则checkMembershipForUser无法正确查询Slack 消息发送失败核对SLACK_BOT_TOKEN是否为有效的xoxb-令牌、SLACK_CHANNEL是否为 Bot 可访问的频道 IDWorker 会在 HTTP 错误或 API 返回ok: false时抛出带状态码/错误码的异常可在wrangler tail日志中定位私钥解析报错确认GITHUB_APP_PRIVATE_KEY已通过openssl pkcs8 -topk8 -inform PEM -outform PEM -nocrypt转换为 PKCS#8 格式改了代码不生效该 Worker 是手动部署务必重新执行npx wrangler deploy并确认部署成功。结语TensorZero 的 Slack Notifications Worker 是一个“小而完整”的无服务器集成范例它以约 230 行的单文件 worker.js 实现了从 Webhook 签名校验、事件过滤、组织成员识别到 Slack 富文本投递的完整闭环配合 README.md 中清晰的部署与 App 配置清单几乎可以照搬到任何开源项目的社区通知场景。理解它的实现也等于掌握了 Cloudflare Workers 与 GitHub Apps、Slack API 三方协作的标准模式。【免费下载链接】tensorzeroTensorZero is an open-source LLMOps platform that unifies an LLM gateway, observability, evaluation, optimization, and experimentation.项目地址: https://gitcode.com/GitHub_Trending/te/tensorzero创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考