From 1fc702ceb422ea4a0de4259c6ceb7818b4bc70b3 Mon Sep 17 00:00:00 2001 From: RhenCloud Date: Mon, 3 Aug 2026 00:39:52 +0800 Subject: [PATCH] docs: add filter tutorial and clarify exact matching rules --- docs/.vitepress/config.ts | 2 + docs/events/supported.md | 2 + docs/guide/configuration.md | 7 +- docs/guide/filters.md | 221 +++++++++++++++++++++++++++++++++ docs/zh/events/supported.md | 86 ++++++------- docs/zh/guide/configuration.md | 7 +- docs/zh/guide/filters.md | 221 +++++++++++++++++++++++++++++++++ 7 files changed, 500 insertions(+), 46 deletions(-) create mode 100644 docs/guide/filters.md create mode 100644 docs/zh/guide/filters.md diff --git a/docs/.vitepress/config.ts b/docs/.vitepress/config.ts index 13a2917..d9e41da 100644 --- a/docs/.vitepress/config.ts +++ b/docs/.vitepress/config.ts @@ -34,6 +34,7 @@ export default defineConfig({ { text: "Introduction", link: "/guide/introduction" }, { text: "Getting Started", link: "/guide/getting-started" }, { text: "Configuration", link: "/guide/configuration" }, + { text: "Filter Tutorial", link: "/guide/filters" }, { text: "Deployment", link: "/guide/deployment" }, ], }, @@ -89,6 +90,7 @@ export default defineConfig({ { text: "简介", link: "/zh/guide/introduction" }, { text: "快速开始", link: "/zh/guide/getting-started" }, { text: "配置", link: "/zh/guide/configuration" }, + { text: "过滤器教程", link: "/zh/guide/filters" }, { text: "部署", link: "/zh/guide/deployment" }, ], }, diff --git a/docs/events/supported.md b/docs/events/supported.md index d97b2b8..c949245 100644 --- a/docs/events/supported.md +++ b/docs/events/supported.md @@ -57,6 +57,8 @@ Any event type without a dedicated formatter falls through to the generic format ## Filter Compatibility +See the [Filter Tutorial](../guide/filters) for a hands-on guide with worked examples. + | Filter | Works With | | --------- | ----------------------------------------------------------------------------------------------------------------------- | | `event` | All events | diff --git a/docs/guide/configuration.md b/docs/guide/configuration.md index 8e15032..cffbce8 100644 --- a/docs/guide/configuration.md +++ b/docs/guide/configuration.md @@ -140,20 +140,23 @@ Routes belong to groups. Groups scope admin access and can restrict which events ## Filter Types +See the [Filter Tutorial](./filters) for a hands-on guide with worked examples. + | Type | Matches | Example | | --------- | -------------------- | -------------------------------- | | `event` | GitHub event name | `push`, `pull_request`, `issues` | | `repo` | Repository full name | `org/repo` | | `actor` | Sender login | `username`, `[bot]` | | `action` | Event action | `opened`, `closed`, `published` | -| `branch` | Branch name | `main`, `feature/*` | +| `branch` | Branch name | `main`, `develop` | | `keyword` | Text in payload body | `deploy`, `/fix\s+\d+/` (regex) | ### Filter Behavior - All filters in a route must match for the route to trigger (AND logic) - Set `"exclude": true` on any filter to invert it (NOT logic) -- `keyword` filter supports regex patterns — falls back to substring match if regex is invalid +- Non-keyword filters are **exact, case-insensitive matches** — no wildcards (`repo: "org/*"` does not match anything) +- `keyword` filter supports regex patterns — falls back to substring match if regex is invalid or longer than 200 characters - `branch` filter works for push, pull_request, pull_request_review, pull_request_review_comment, create/delete, workflow_run, and code_scanning_alert events ### Match Values diff --git a/docs/guide/filters.md b/docs/guide/filters.md new file mode 100644 index 0000000..eddc196 --- /dev/null +++ b/docs/guide/filters.md @@ -0,0 +1,221 @@ +# Filter Tutorial + +Filters decide which webhook events a [route](./configuration#routes) forwards. A route fires only when **every** filter in its `filters` array matches (AND logic). This page is a hands-on tutorial: it explains how each filter type behaves and how to combine them into real-world routing rules. + +See [Filter Types](./configuration#filter-types) in the configuration guide for the reference table, and [Supported Events](../events/supported) for the full event list. + +## How Matching Works + +- All filters in a route must match, otherwise the route is skipped. +- Each filter matches the event against one field of the webhook payload. +- Matching is **case-insensitive** and **exact**: `main` matches `main`, `Main`, and `MAIN`, but not `main-v2`. +- The `match` value accepts either a single string or an array of strings. An array behaves as OR — the filter matches if any of its values match. +- Setting `"exclude": true` inverts the result (NOT logic): the filter matches when the value does **not** equal the match value. + +```json +{ + "type": "event", + "match": ["push", "pull_request"], + "exclude": false +} +``` + +The route above matches both `push` and `pull_request` events. + +## Filter Types in Depth + +### `event` — Event type + +Matches the GitHub event name, e.g. `push`, `pull_request`, `issues`, `release`. Use this as the backbone of every route. + +```json +{ "type": "event", "match": "release" } +``` + +Match several events with an array: + +```json +{ "type": "event", "match": ["create", "delete"] } +``` + +### `repo` — Repository + +Matches the repository **full name** (`owner/name`). Case-insensitive. + +```json +{ "type": "repo", "match": "myorg/backend" } +``` + +Route multiple repositories to one channel: + +```json +{ "type": "repo", "match": ["myorg/backend", "myorg/frontend"] } +``` + +### `actor` — Sender + +Matches the **sender's GitHub login** that triggered the event (`sender.login` in the payload). Useful for ignoring bots. + +```json +{ "type": "actor", "match": "dependabot[bot]", "exclude": true } +``` + +The route above fires for every event **except** those triggered by Dependabot. + +### `action` — Event action + +Matches the `action` field of the payload, e.g. `opened`, `closed`, `published`, `completed`. Not all events carry an action — see [Filter Compatibility](../events/supported#filter-compatibility). Combine it with `event` to narrow down a specific lifecycle step: + +```json +{ + "type": "event", + "match": "pull_request", + "exclude": false +}, +{ + "type": "action", + "match": ["opened", "reopened"] +} +``` + +This fires when a pull request is opened or reopened (and not on merge/close/edit). + +### `branch` — Branch + +Matches the branch involved in the event. What counts as "the branch" depends on the event type: + +| Event | Branch extracted | +| --------------------------- | ------------------------------------------- | +| `push` | The branch that was pushed to | +| `pull_request` (and review) | The pull request's **head** (source) branch | +| `create` / `delete` | The created/deleted branch or tag | +| `workflow_run` | The `head_branch` the workflow ran on | +| `code_scanning_alert` | The branch the alert belongs to | + +```json +{ + "type": "event", + "match": "push" +}, +{ + "type": "branch", + "match": "main" +} +``` + +Fires for pushes to `main` only. To watch several long-lived branches: + +```json +{ "type": "branch", "match": ["main", "develop"] } +``` + +> [!NOTE] +> `branch` matching is **exact and case-insensitive**, not a glob or prefix match. A value like `feature/*` will **not** work. For prefix or wildcard-style matching, use the `keyword` filter on the payload (see below). + +### `keyword` — Text in the payload + +Matches against the **full JSON payload**, lowercased. It supports regular expressions, so it is the most flexible filter. The pattern is compiled with the `i` (case-insensitive) flag. + +```json +{ "type": "keyword", "match": "/deploy/started/i" } +``` + +Fires when the payload contains `deploy/started` anywhere. Because the payload is lowercased, the `i` flag is optional but harmless. + +A few practical examples: + +```json +{ "type": "keyword", "match": "/dependabot/" } +``` + +```json +{ "type": "keyword", "match": "/^(fix|hotfix)/" } +``` + +```json +{ "type": "keyword", "match": "/release-[0-9]+/" } +``` + +Behavior details: + +- Patterns longer than 200 characters are **not** compiled as regex and fall back to plain substring matching. +- If a pattern is not a valid regex, it also falls back to substring matching instead of erroring. +- To search for text that is a regex special character (e.g. `v1.2.3`), you can rely on the substring fallback and omit the regex syntax — a pattern without regex metacharacters behaves the same either way. +- The search covers the **entire** payload: commit messages, PR titles and bodies, labels, refs, even repository and sender names. + +### Combining `exclude` with `keyword` + +Just like the other filters, `exclude` inverts the keyword match: + +```json +{ "type": "keyword", "match": "/wip|draft/", "exclude": true } +``` + +Skips events whose payload mentions `wip` or `draft`. + +## Worked Example 1: PR alerts that skip bots and drafts + +Forward pull request activity, but ignore bot authors and draft PRs, to a `#prs` channel: + +```json +{ + "id": "pr-notices", + "name": "PR Notices", + "enabled": true, + "groupId": "eng", + "filters": [ + { "type": "event", "match": "pull_request" }, + { "type": "actor", "match": "dependabot[bot]", "exclude": true }, + { "type": "keyword", "match": "\"draft\": true", "exclude": true } + ], + "target": { "channelId": "111111111111111111" } +} +``` + +The `"draft": true` pattern matches the `draft` field that GitHub includes in pull request payloads; combined with `exclude: true` it filters out draft PRs. + +## Worked Example 2: Release-only channel + +Forward only published releases from a specific repo: + +```json +{ + "id": "release-alerts", + "name": "Release Alerts", + "enabled": true, + "groupId": "eng", + "filters": [ + { "type": "event", "match": "release" }, + { "type": "action", "match": "published" }, + { "type": "repo", "match": "myorg/backend" } + ], + "target": { "channelId": "222222222222222222" } +} +``` + +## Worked Example 3: CI failures + +Forward workflow runs that ended in failure on any branch, to a `#ci` channel: + +```json +{ + "id": "ci-failures", + "name": "CI Failures", + "enabled": true, + "groupId": "eng", + "filters": [ + { "type": "event", "match": "workflow_run" }, + { "type": "action", "match": "completed" }, + { "type": "keyword", "match": "\"conclusion\":\"failure\"" } + ], + "target": { "channelId": "333333333333333333" } +} +``` + +## Common Pitfalls + +- **No wildcards on non-keyword filters.** `event`, `repo`, `actor`, `action`, and `branch` are exact matches. `repo: "myorg/*"` will not match anything. +- **An `action` filter on an action-less event never matches.** Check the event has an `action` field first (see [Filter Compatibility](../events/supported#filter-compatibility)). +- **`branch` on an event without a branch never matches.** A `branch` filter on an `issues` event will always be false. Use `keyword` if you need branch-like matching there. +- **`keyword` searches everything.** Because it scans the whole payload, a pattern like `"fix"` can match commit messages, issue titles, _and_ repository names. Be as specific as possible. +- **Forgetting `exclude` semantics.** `exclude: true` negates the whole filter — one non-matching value in an array does not "block" the route; the negated filter matches only when _none_ of the values match. diff --git a/docs/zh/events/supported.md b/docs/zh/events/supported.md index 28f8eac..d973a1f 100644 --- a/docs/zh/events/supported.md +++ b/docs/zh/events/supported.md @@ -4,46 +4,46 @@ WebHooker 支持 23 种 GitHub webhook 事件类型，每种都有专用的格 ## 事件表 -| 事件 | 说明 | 嵌入亮点 | -| --- | --- | --- | -| `push` | 代码推送到分支 | 提交列表、分支、作者、差异统计 | -| `pull_request` | PR 打开/关闭/合并/编辑 | PR 标题、分支、差异统计、标签 | -| `issues` | 议题打开/关闭/编辑 | 议题标题、标签、指派人 | -| `issue_comment` | 议题或 PR 的评论 | 评论内容、议题引用 | -| `workflow_run` | CI/CD 工作流完成 | 工作流状态、结论、耗时 | -| `release` | 发布创建/编辑 | 标签、内容、附件、预发布标记 | -| `create` | 分支或标签已创建 | 引用名称、引用类型 | -| `delete` | 分支或标签已删除 | 引用名称、引用类型 | -| `star` | 仓库加星/取消星标 | 星标数、操作 | -| `fork` | 仓库已复刻 | 源 → 目标复刻 | -| `check_run` | 检查运行完成 | 状态、结论、详情 URL | -| `pull_request_review` | PR 审查已提交 | 审查状态（已批准/需修改/已评论）、正文 | -| `pull_request_review_comment` | 行内代码审查评论 | 文件路径、行号、评论内容 | -| `commit_comment` | 提交的评论 | 提交 SHA、评论内容 | -| `deployment_status` | 部署状态更新 | 环境、状态、提交引用 | -| `member` | 协作者添加/移除 | 成员登录名、操作 | -| `label` | 标签创建/编辑/删除 | 标签名称、颜色、描述 | -| `milestone` | 里程碑打开/关闭 | 进度条、议题计数、截止日期 | -| `discussion` | 讨论创建/回答 | 标题、分类、操作 | -| `discussion_comment` | 讨论的评论 | 评论内容、讨论引用 | -| `repository` | 仓库重命名/转移 | 旧 → 新名称、变更 | -| `code_scanning_alert` | 代码扫描告警 | 严重程度、规则 ID、文件路径 | -| `dependabot_alert` | Dependabot 告警 | 严重程度、包、受影响版本、修复版本 | +| 事件 | 说明 | 嵌入亮点 | +| ----------------------------- | ---------------------- | -------------------------------------- | +| `push` | 代码推送到分支 | 提交列表、分支、作者、差异统计 | +| `pull_request` | PR 打开/关闭/合并/编辑 | PR 标题、分支、差异统计、标签 | +| `issues` | 议题打开/关闭/编辑 | 议题标题、标签、指派人 | +| `issue_comment` | 议题或 PR 的评论 | 评论内容、议题引用 | +| `workflow_run` | CI/CD 工作流完成 | 工作流状态、结论、耗时 | +| `release` | 发布创建/编辑 | 标签、内容、附件、预发布标记 | +| `create` | 分支或标签已创建 | 引用名称、引用类型 | +| `delete` | 分支或标签已删除 | 引用名称、引用类型 | +| `star` | 仓库加星/取消星标 | 星标数、操作 | +| `fork` | 仓库已复刻 | 源 → 目标复刻 | +| `check_run` | 检查运行完成 | 状态、结论、详情 URL | +| `pull_request_review` | PR 审查已提交 | 审查状态（已批准/需修改/已评论）、正文 | +| `pull_request_review_comment` | 行内代码审查评论 | 文件路径、行号、评论内容 | +| `commit_comment` | 提交的评论 | 提交 SHA、评论内容 | +| `deployment_status` | 部署状态更新 | 环境、状态、提交引用 | +| `member` | 协作者添加/移除 | 成员登录名、操作 | +| `label` | 标签创建/编辑/删除 | 标签名称、颜色、描述 | +| `milestone` | 里程碑打开/关闭 | 进度条、议题计数、截止日期 | +| `discussion` | 讨论创建/回答 | 标题、分类、操作 | +| `discussion_comment` | 讨论的评论 | 评论内容、讨论引用 | +| `repository` | 仓库重命名/转移 | 旧 → 新名称、变更 | +| `code_scanning_alert` | 代码扫描告警 | 严重程度、规则 ID、文件路径 | +| `dependabot_alert` | Dependabot 告警 | 严重程度、包、受影响版本、修复版本 | ## 颜色编码 每种事件类型在 Discord 嵌入中使用不同的颜色： -| 颜色 | 事件 | -| --- | --- | +| 颜色 | 事件 | +| ---------------- | ---------------------------------------------------------- | | 绿色 (`#2ea44f`) | push、issue 打开、PR 打开、release 发布、star、member 添加 | -| 红色 (`#d73a49`) | issue 关闭、PR 关闭、deployment 失败、dependabot 严重 | -| 紫色 (`#7057ff`) | PR 合并、discussion 创建 | -| 蓝色 (`#0366d6`) | PR review 评论、issue 评论、workflow run | -| 黄色 (`#dbab09`) | PR review 请求修改、deployment 待定 | -| 青色 (`#00897b`) | check run、code scanning | -| 橙色 (`#e67e22`) | label、milestone | -| 灰色 (`#6a737d`) | delete、repository、member 移除 | +| 红色 (`#d73a49`) | issue 关闭、PR 关闭、deployment 失败、dependabot 严重 | +| 紫色 (`#7057ff`) | PR 合并、discussion 创建 | +| 蓝色 (`#0366d6`) | PR review 评论、issue 评论、workflow run | +| 黄色 (`#dbab09`) | PR review 请求修改、deployment 待定 | +| 青色 (`#00897b`) | check run、code scanning | +| 橙色 (`#e67e22`) | label、milestone | +| 灰色 (`#6a737d`) | delete、repository、member 移除 | ## 通用回退 @@ -57,11 +57,13 @@ WebHooker 支持 23 种 GitHub webhook 事件类型，每种都有专用的格 ## 过滤器兼容性 -| 过滤器 | 适用事件 | -| --- | --- | -| `event` | 所有事件 | -| `repo` | 所有事件 | -| `actor` | 所有事件 | -| `action` | 载荷中包含 `action` 字段的事件 | -| `branch` | push、pull_request、pull_request_review、pull_request_review_comment、create、delete、workflow_run、code_scanning_alert | -| `keyword` | 所有事件（搜索完整载荷正文） | +实操指南见[过滤器教程](../guide/filters)，包含完整示例。 + +| 过滤器 | 适用事件 | +| --------- | ----------------------------------------------------------------------------------------------------------------------- | +| `event` | 所有事件 | +| `repo` | 所有事件 | +| `actor` | 所有事件 | +| `action` | 载荷中包含 `action` 字段的事件 | +| `branch` | push、pull_request、pull_request_review、pull_request_review_comment、create、delete、workflow_run、code_scanning_alert | +| `keyword` | 所有事件（搜索完整载荷正文） | diff --git a/docs/zh/guide/configuration.md b/docs/zh/guide/configuration.md index 50256a5..f9863ca 100644 --- a/docs/zh/guide/configuration.md +++ b/docs/zh/guide/configuration.md @@ -140,20 +140,23 @@ WebHooker 内置了位于 `/admin` 的配置控制台，可在浏览器中管理 ## 过滤器类型 +实操指南见[过滤器教程](./filters)，包含完整示例。 + | 类型 | 匹配对象 | 示例 | | --------- | ---------------- | -------------------------------- | | `event` | GitHub 事件名称 | `push`, `pull_request`, `issues` | | `repo` | 仓库全名 | `org/repo` | | `actor` | 发送者登录名 | `username`, `[bot]` | | `action` | 事件操作 | `opened`, `closed`, `published` | -| `branch` | 分支名称 | `main`, `feature/*` | +| `branch` | 分支名称 | `main`, `develop` | | `keyword` | 载荷正文中的文本 | `deploy`, `/fix\s+\d+/` (正则) | ### 过滤器行为 - 路由中的所有过滤器必须都匹配才触发路由（AND 逻辑） - 在任何过滤器上设置 `"exclude": true` 可反转匹配逻辑（NOT 逻辑） -- `keyword` 过滤器支持正则表达式——如果正则有误，回退到子串匹配 +- 非 keyword 过滤器为**精确、不区分大小写**的匹配——不支持通配符（`repo: "org/*"` 不会匹配任何内容） +- `keyword` 过滤器支持正则表达式——正则有误或超过 200 个字符时回退到子串匹配 - `branch` 过滤器适用于 push、pull_request、pull_request_review、pull_request_review_comment、create/delete、workflow_run 和 code_scanning_alert 事件 ### 匹配值 diff --git a/docs/zh/guide/filters.md b/docs/zh/guide/filters.md new file mode 100644 index 0000000..b451c75 --- /dev/null +++ b/docs/zh/guide/filters.md @@ -0,0 +1,221 @@ +# 过滤器教程 + +过滤器决定哪些 Webhook 事件会被[路由](./configuration#路由)转发。只有当路由 `filters` 数组中的**每一个**过滤器都匹配时，路由才会触发（AND 逻辑）。本页是一份上手教程：解释每种过滤器类型的行为，以及如何组合它们实现真实场景的路由规则。 + +参考表格见配置指南的[过滤器类型](./configuration#过滤器类型)，完整事件列表见[支持的事件](../events/supported)。 + +## 匹配机制 + +- 路由中所有过滤器都必须匹配，否则该路由被跳过。 +- 每个过滤器将事件与 Webhook 载荷的某个字段进行匹配。 +- 匹配**不区分大小写且为精确匹配**：`main` 能匹配 `main`、`Main`、`MAIN`，但不能匹配 `main-v2`。 +- `match` 值可以是单个字符串，也可以是字符串数组。数组相当于 OR——只要其中一个值匹配，该过滤器即匹配。 +- 设置 `"exclude": true` 会反转结果（NOT 逻辑）：当值**不**等于 match 值时，该过滤器才匹配。 + +```json +{ + "type": "event", + "match": ["push", "pull_request"], + "exclude": false +} +``` + +上面这条路由同时匹配 `push` 和 `pull_request` 事件。 + +## 各过滤器类型详解 + +### `event` — 事件类型 + +匹配 GitHub 事件名称，如 `push`、`pull_request`、`issues`、`release`。它是每条路由的主干。 + +```json +{ "type": "event", "match": "release" } +``` + +用数组匹配多种事件： + +```json +{ "type": "event", "match": ["create", "delete"] } +``` + +### `repo` — 仓库 + +匹配仓库**全名**（`owner/name`）。不区分大小写。 + +```json +{ "type": "repo", "match": "myorg/backend" } +``` + +将多个仓库路由到同一频道： + +```json +{ "type": "repo", "match": ["myorg/backend", "myorg/frontend"] } +``` + +### `actor` — 发送者 + +匹配触发事件的 **GitHub 发送者登录名**（载荷中的 `sender.login`）。常用于忽略机器人。 + +```json +{ "type": "actor", "match": "dependabot[bot]", "exclude": true } +``` + +上面这条路由对**除** Dependabot 触发之外的所有事件都会触发。 + +### `action` — 事件操作 + +匹配载荷中的 `action` 字段，如 `opened`、`closed`、`published`、`completed`。并非所有事件都带有 action——参见[过滤器兼容性](../events/supported#过滤器兼容性)。与 `event` 组合可精确到某个生命周期步骤： + +```json +{ + "type": "event", + "match": "pull_request", + "exclude": false +}, +{ + "type": "action", + "match": ["opened", "reopened"] +} +``` + +上面的规则在拉取请求被打开或重新打开时触发（合并/关闭/编辑时不触发）。 + +### `branch` — 分支 + +匹配事件涉及的分支。何种字段算作「分支」取决于事件类型： + +| 事件 | 提取的分支 | +| --------------------------- | ------------------------------ | +| `push` | 推送到的目标分支 | +| `pull_request`（及 review） | 拉取请求的 **head**（源）分支 | +| `create` / `delete` | 创建/删除的分支或标签 | +| `workflow_run` | 工作流运行所在的 `head_branch` | +| `code_scanning_alert` | 告警所属的分支 | + +```json +{ + "type": "event", + "match": "push" +}, +{ + "type": "branch", + "match": "main" +} +``` + +仅当推送到 `main` 时触发。要关注多个长期分支： + +```json +{ "type": "branch", "match": ["main", "develop"] } +``` + +> [!NOTE] +> `branch` 匹配是**精确且不区分大小写**的，不是通配符或前缀匹配。`feature/*` 这样的值**不会**生效。需要前缀或通配符式匹配时，请改用 `keyword` 过滤器匹配载荷（见下）。 + +### `keyword` — 载荷中的文本 + +匹配整个 JSON 载荷（转为小写）。它支持正则表达式，因此是最灵活的过滤器。模式以 `i`（忽略大小写）标志编译。 + +```json +{ "type": "keyword", "match": "/deploy/started/i" } +``` + +当载荷中任意位置包含 `deploy/started` 时触发。由于载荷已被转为小写，`i` 标志可有可无但无副作用。 + +一些实用示例： + +```json +{ "type": "keyword", "match": "/dependabot/" } +``` + +```json +{ "type": "keyword", "match": "/^(fix|hotfix)/" } +``` + +```json +{ "type": "keyword", "match": "/release-[0-9]+/" } +``` + +行为细节： + +- 超过 200 个字符的模式**不**编译为正则，回退为纯子串匹配。 +- 如果某模式不是合法正则，也会回退为子串匹配，而不是报错。 +- 要搜索是正则特殊字符的文本（如 `v1.2.3`），可以省略正则语法直接依赖子串回退——不含正则元字符的模式两种方式行为相同。 +- 搜索覆盖**整个**载荷：提交信息、PR 标题与正文、标签、引用，甚至仓库名和发送者名。 + +### `keyword` 与 `exclude` 组合 + +与其他过滤器一样，`exclude` 会反转关键词匹配： + +```json +{ "type": "keyword", "match": "/wip|draft/", "exclude": true } +``` + +跳过载荷中提及 `wip` 或 `draft` 的事件。 + +## 示例 1：PR 通知，跳过机器人和草稿 + +转发拉取请求动态，但忽略机器人作者和草稿 PR，发往 `#prs` 频道： + +```json +{ + "id": "pr-notices", + "name": "PR Notices", + "enabled": true, + "groupId": "eng", + "filters": [ + { "type": "event", "match": "pull_request" }, + { "type": "actor", "match": "dependabot[bot]", "exclude": true }, + { "type": "keyword", "match": "\"draft\": true", "exclude": true } + ], + "target": { "channelId": "111111111111111111" } +} +``` + +`"draft": true` 模式匹配 GitHub 在拉取请求载荷中包含的 `draft` 字段；配合 `exclude: true` 即可过滤掉草稿 PR。 + +## 示例 2：仅发布通知频道 + +只转发特定仓库的已发布 release： + +```json +{ + "id": "release-alerts", + "name": "Release Alerts", + "enabled": true, + "groupId": "eng", + "filters": [ + { "type": "event", "match": "release" }, + { "type": "action", "match": "published" }, + { "type": "repo", "match": "myorg/backend" } + ], + "target": { "channelId": "222222222222222222" } +} +``` + +## 示例 3：CI 失败 + +转发任意分支上以失败结束的 workflow run，发往 `#ci` 频道： + +```json +{ + "id": "ci-failures", + "name": "CI Failures", + "enabled": true, + "groupId": "eng", + "filters": [ + { "type": "event", "match": "workflow_run" }, + { "type": "action", "match": "completed" }, + { "type": "keyword", "match": "\"conclusion\":\"failure\"" } + ], + "target": { "channelId": "333333333333333333" } +} +``` + +## 常见陷阱 + +- **非 keyword 过滤器不支持通配符。** `event`、`repo`、`actor`、`action`、`branch` 都是精确匹配。`repo: "myorg/*"` 不会匹配任何内容。 +- **`action` 过滤器遇到无 action 的事件永远不匹配。** 先确认该事件带有 `action` 字段（见[过滤器兼容性](../events/supported#过滤器兼容性)）。 +- **`branch` 过滤器遇到无分支的事件永远不匹配。** 在 `issues` 事件上使用 `branch` 过滤器恒为假。此时需要类似分支的匹配可用 `keyword`。 +- **`keyword` 会搜索一切。** 因为它扫描整个载荷，`"fix"` 这样的模式可能同时匹配提交信息、issue 标题和仓库名。请尽量写得更具体。 +- **牢记 `exclude` 语义。** `exclude: true` 反转的是整个过滤器——数组中的一个值不匹配并不会「阻断」路由；只有当**所有**值都不匹配时，取反后的过滤器才匹配。