feat(github): fetch workflow_run jobs via jobs_url enrichment

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)
This commit is contained in:
RhenCloud committed 2026-09-26 15:33:06 +08:00
1 parent ae36c22fda
commit 04352c3a19
12 files changed
+223 -23

No files matched your search

+2
View File
@@ -62,6 +62,8 @@ Any event type without a dedicated formatter falls through to the generic format
`workflow_run` and `check_run` events (queued → running → success/failure) are sent once and then **edited in place** for each subsequent phase instead of posting a new message. The original message's link preview, author, and field layout are preserved; only the status, conclusion emoji, duration, and title are refreshed. Supported on both Discord (`editMessage`) and Telegram (`editMessageText` / `editMessageCaption`). `check_run` tracks by check name + commit SHA (falling back to the run id), so providers that issue a new run id per phase — e.g. Cloudflare Pages — still edit the same message.
`workflow_run` messages also carry a colored **Jobs** breakdown. Because the webhook payload itself has no job list (only a `jobs_url`), the worker fetches it from the GitHub API — authenticated with a GitHub App installation token when `GITHUB_APP_ID` / `GITHUB_PRIVATE_KEY` are set, otherwise unauthenticated (public repositories). The App therefore needs the **Actions: read** repository permission.
## Filter Compatibility
See the [Filter Tutorial](../guide/filters) for a hands-on guide with worked examples.
+3 -3
View File
@@ -40,7 +40,7 @@ There is no global channel secret. Each route in the [Web UI](/guide/configurati
:::
::: tip GitHub App ID / private key are optional
`GITHUB_APP_ID` + `GITHUB_PRIVATE_KEY` (PKCS#8 PEM) are only used by the [App install flow](#github-app-setup) to resolve the installing account's login on the post-install choice page. You can skip them — the page then shows an anonymous `inst-{installationId}` group. The OAuth flow only needs `GITHUB_CLIENT_ID` / `GITHUB_CLIENT_SECRET`.
`GITHUB_APP_ID` + `GITHUB_PRIVATE_KEY` (PKCS#8 PEM) are used by the [App install flow](#github-app-setup) to resolve the installing account's login on the post-install choice page, and to mint installation tokens for API enrichment — fetching `workflow_run` job lists and check-suite build logs. You can skip them — the install page then shows an anonymous `inst-{installationId}` group, workflow job lists still load for public repositories (unauthenticated), and private-repo build logs are omitted. The OAuth flow only needs `GITHUB_CLIENT_ID` / `GITHUB_CLIENT_SECRET`.
:::
Discord interactions arrive via the HTTPS Interactions Endpoint, so set `DISCORD_PUBLIC_KEY` and point the **Interactions Endpoint URL** at `https://your-domain/discord/interactions`. See [Interactions Endpoint](#interactions-endpoint) below.
@@ -144,11 +144,11 @@ Your worker is now live at `https://webhooker.<your-subdomain>.workers.dev`.
- **Webhook URL**: `https://your-domain/webhook`
- **Webhook secret**: generate and copy to `GITHUB_WEBHOOK_SECRET`
3. Set permissions:
- **Repository permissions**: Contents (read), Issues (write), Pull requests (write), Metadata (read), Checks (read), Deployments (read), Discussions (read), Code scanning alerts (read), Dependabot alerts (read)
- **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) — if needed
4. Subscribe to events (all 28 supported):
- 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
5. Generate private key — optional; set `GITHUB_APP_ID` + `GITHUB_PRIVATE_KEY` to show the installing account's login on the post-install page (see the tip above).
5. Generate private key — optional; set `GITHUB_APP_ID` + `GITHUB_PRIVATE_KEY` to show the installing account's login on the post-install page and to authenticate API enrichment (workflow job lists, build logs) for private repositories (see the tip above).
### 2. Install App
+2
View File
@@ -47,3 +47,5 @@ With `Group.forgeSources` (a list of `{ host, type, name? }` entries) the messag
```
Each line is `{name} {emoji}{status}` plus the job duration when it has completed. Successful jobs are prefixed with `+` (green), failed/other finished jobs with `-` (red), and running/queued/pending jobs use a plain space (no color). The job name is clamped to 200 chars and the whole field to the platform field limit. Drivers without diff support (Telegram, Feishu) render the block as a single inline code span.
The `workflow_run` webhook payload itself carries no job list — only a `jobs_url`. The worker fetches the jobs from that URL (one GitHub API call per delivery, skipped when no route matches): authenticated with a GitHub App installation token when `GITHUB_APP_ID` / `GITHUB_PRIVATE_KEY` are configured, otherwise unauthenticated (public repositories only). The App therefore needs the **Actions: read** repository permission. If the fetch fails (missing permission, private repo without App creds, rate limit) the message simply omits the Jobs field.
+2
View File
@@ -62,6 +62,8 @@ WebHooker 支持 28 种 GitHub webhook 事件类型,每种都有专用的格
`workflow_run` / `check_run` 事件(queued → running → success/failure)只发送一条消息,后续每个阶段会**原地编辑**该消息,而不是发送新消息。消息的链接预览、作者和字段布局保持不变,仅刷新状态、结论 emoji、耗时和标题。Discord(`editMessage`)和 Telegram(`editMessageText` / `editMessageCaption`)均支持。`check_run` 以 check 名 + commit SHA 追踪(回退到 run id),因此每个阶段都会换新 run id 的提供方(例如 Cloudflare Pages)仍会编辑同一条消息。
`workflow_run` 消息还会附带带颜色的 **Jobs** 明细。由于 webhook 载荷本身不含作业列表(只有 `jobs_url`),Worker 会从 GitHub API 拉取——配置了 `GITHUB_APP_ID` / `GITHUB_PRIVATE_KEY` 时用 GitHub App 安装令牌鉴权,否则匿名请求(公开仓库)。因此 App 需要 **Actions: read** 仓库权限。
## 过滤器兼容性
实操指南见[过滤器教程](../guide/filters),包含完整示例。
+3 -3
View File
@@ -40,7 +40,7 @@ bunx wrangler secret put ADMIN_USER_IDS # 逗号分隔的 GitHub ID/登录
:::
::: tip GitHub App ID / 私钥为可选
`GITHUB_APP_ID` + `GITHUB_PRIVATE_KEY`(PKCS#8 PEM)仅用于 [App 安装流程](#github-app-设置),在安装后选择页解析安装所属账号的登录名。可以跳过不设——页面会显示匿名 `inst-{installationId}` 分组。OAuth 流程只需要 `GITHUB_CLIENT_ID` / `GITHUB_CLIENT_SECRET`。
`GITHUB_APP_ID` + `GITHUB_PRIVATE_KEY`(PKCS#8 PEM)用于 [App 安装流程](#github-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](#interactions-endpoint)。
@@ -144,11 +144,11 @@ Worker 现在可通过 `https://webhooker.<your-subdomain>.workers.dev` 访问
- **Webhook URL**: `https://your-domain/webhook`
- **Webhook secret**: 生成并复制到 `GITHUB_WEBHOOK_SECRET`
3. 设置权限:
- **Repository permissions**: Contents (read)、Issues (write)、Pull requests (write)、Metadata (read)、Checks (read)、Deployments (read)、Discussions (read)、Code scanning alerts (read)、Dependabot alerts (read)
- **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) —— 如果需要
4. 订阅事件(全部 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
5. 生成私钥 — 可选;设置 `GITHUB_APP_ID` + `GITHUB_PRIVATE_KEY` 后,安装后页面会显示安装所属账号的登录名(见上方提示)。
5. 生成私钥 — 可选;设置 `GITHUB_APP_ID` + `GITHUB_PRIVATE_KEY` 后,安装后页面会显示安装所属账号的登录名,并以安装令牌鉴权私有仓库的 API 增强(作业列表、构建日志)(见上方提示)。
### 2. 安装 App
+2
View File
@@ -47,3 +47,5 @@
```
每行格式为 `{作业名} {emoji}{状态}`,作业完成后追加耗时。成功的作业以 `+` 前缀(绿色),失败/其他已结束的作业以 `-` 前缀(红色),运行中/排队中/待定的作业使用普通空格(无颜色)。作业名截断至 200 字符,整个字段截断至平台字段上限。不支持 diff 的驱动(Telegram、飞书)会把该代码块渲染为单个行内代码片段。
`workflow_run` 的 webhook 载荷本身不含作业列表,只有 `jobs_url`。Worker 会从该 URL 拉取作业(每次投递一次 GitHub API 调用,没有路由命中时跳过):配置了 `GITHUB_APP_ID` / `GITHUB_PRIVATE_KEY` 时用 GitHub App 安装令牌鉴权,否则匿名请求(仅公开仓库)。因此 App 需要 **Actions: read** 仓库权限。若拉取失败(缺少权限、私有仓库且未配置 App 凭据、触发限流),消息直接省略 Jobs 字段。