mirror of
https://github.com/ReCloudStudio/WebHooker.git
synced 2026-09-22 16:11:29 +00:00
docs: add filter tutorial and clarify exact matching rules
This commit is contained in:
parent
8c9720b1b3
commit
1fc702ceb4
7 changed files with 500 additions and 46 deletions
|
|
@ -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" },
|
||||
],
|
||||
},
|
||||
|
|
|
|||
|
|
@ -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 |
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
221
docs/guide/filters.md
Normal file
221
docs/guide/filters.md
Normal file
|
|
@ -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.
|
||||
|
|
@ -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` | 所有事件（搜索完整载荷正文） |
|
||||
|
|
|
|||
|
|
@ -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 事件
|
||||
|
||||
### 匹配值
|
||||
|
|
|
|||
221
docs/zh/guide/filters.md
Normal file
221
docs/zh/guide/filters.md
Normal file
|
|
@ -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` 反转的是整个过滤器——数组中的一个值不匹配并不会「阻断」路由；只有当**所有**值都不匹配时，取反后的过滤器才匹配。
|
||||
Loading…
Add table
Add a link
Reference in a new issue