Files
WebHooker/docs/guide/filters.md
T
翅膀喵 dbf162bf74 feat(admin-console): improve route and filter management (#10)
* fix(nuxt): pre-bundle the CommonJS deps of the markdown stack

`debug` and `extend` are imported by micromark and unified through
@elysola/ui. Served unbundled by the dev server they have no default
export, so the console page failed with a 500 in `nuxt dev`.

* docs(deployment): list the fragments and feishu link migrations

The manual `d1 execute` fallback stopped at 0008, and AGENTS.md named
0001..0010 although 0011 already exists.

* feat(storage): persist the per-group route order

Routes used to load in id order, so the order saved from the console
was lost on the next read. Migration 0012 adds `d1_routes.position`:
saving writes each route's index within its own group (saving one group
never shifts another), and routes load by `group_id, position, id`.

A database without the column keeps working: only a "no such column" /
"has no column named" error falls back to the legacy statements, and
nothing is cached, so a later migration is picked up on the next call.

* feat(console): add in-app destructive-action confirmation

Deleting a route or a group used `window.confirm`, which blocks the page
and ignores the console theme. A promise-based `useConfirm()` now drives
one <ConfirmDialog /> built on the reka-ui AlertDialog that
@elysola/ui ships; reka-ui is pre-bundled so dev keeps a single copy and
the dialog stacks with the Rc dialogs.

A request never outlives its asker: one made after the asking component
unmounted resolves false, and one still open when it unmounts is
cancelled.

* feat(console): confirm member and webhook removal

Removing a member, revoking an invite link and disabling a group's
webhook endpoint took effect on the first click. They now ask first;
disabling the webhook explains that senders still using the secret will
be rejected, and its button is styled as destructive.

* feat(console): confirm removing filled editor rows

Filter conditions and groups, delivery targets, saved fragments and forge
hosts vanished on a single click, taking whatever had been typed with
them. Rows holding content now ask first, while empty, never-filled
rows (`isBlankNode`: default operator, no path, no values, not negated)
are still removed directly.

* fix(i18n): remove duplicate button glyphs

"New Route", "New Group" and the group cards' "Open" link render a Plus
or ArrowRight icon next to their label, so the "+" and "→" baked into
the strings appeared twice.

* style(console): redesign route cards for narrow screens

The card was one flex row whose badges, filter chips, targets and five
hand-drawn icon buttons squeezed the route name on small screens. It is
now a grid driven by a container query: name and actions share the top
line, the filter summary (clamped to two lines) and targets follow, and
the tags wrap below; from 40rem the tags move up beside the title.

Targets of the same platform collapse into one tag with a count, long
ids truncate instead of widening the page, and the actions use lucide
icons with accessible labels.

* feat(console): reorder a group's routes by drag or keyboard

The per-card up/down arrows saved after every single step, so moving a
route five places took five writes. A Reorder mode on the group page now
swaps each card's switch for a drag handle: pointer drags (mouse and
touch) slide the neighbours out of the way and auto-scroll near the
viewport edges, Arrow Up/Down on a focused handle moves a card by one
and is announced to screen readers, and nothing is written until Save
order. Cancel or Escape (unless a dialog or list owns it) drops the
draft.

The cards move into a new RouteList component that owns the drag state.

* style(members): align member cards and invite actions

* style(group-editor): size forge and log target controls

Keep source hosts, platform selectors and remove actions aligned without stretching short controls across the dialog. Wrap component roots explicitly so their internal markup cannot break the grid.

* style(route-editor): group options and delivery target fields

Give each target labeled fields and a compact platform header, widen the filter workspace, and align fragment controls. Scroll failed validation into view when the footer is far from the affected section.

* feat(filters): add bilingual suggestions and value validation

Catalog forge events, actions, payload paths and known values with searchable English and Chinese descriptions. Match-value validation mirrors the server and only rejects inputs that cannot match.

* feat(filters): add searchable creatable value inputs

Build a theme-aligned combobox on the shared reka-ui primitives. Rank stored keys before bilingual descriptions, allow validated custom values, and preserve unconfirmed multi-value drafts instead of silently committing them.

* feat(filter-editor): integrate searchable condition inputs

Replace chip-only values with context-aware bilingual inputs and a compact condition grid. Preserve drafts across tree changes, block saves and tests until drafts are resolved, and keep keyword filters free of hidden operators.

* feat(filters): split pasted values without breaking regexes

Accept multiple values separated by commas or lines while retaining commas inside wrapped expressions and raw regex patterns. Pasting replaces the selected range and keeps rejected values as an explicit draft.

* fix(filters): adapt suggestions to the selected operator

Offer literal prefixes and suffixes for substring operators, escaped anchored patterns for regex, and numeric suggestions only for comparisons. Suggestion syntax must mean what the selected matcher actually reads.

* fix(filters): preserve regex meaning when changing operators

Swap wrapped and raw regex sources only when both compile identically after saving. Leave literal, glob, multiline and Unicode-sensitive comparisons unchanged rather than inventing non-equivalent conversions.

* a11y(filter-editor): label type and operator controls

Associate each fixed select with a stable per-condition label while keeping the compact visual layout unchanged.

* fix(editors): ignore accidental backdrop dismissal

Do not discard unsaved route or group edits when the user clicks outside the dialog. Preserve Escape, Cancel and explicit close, including popovers and confirmation dialogs stacked above the editor.

* feat(dispatch)!: scope stop and fallback to each group

A match in one group must not suppress delivery in another group. Track regular matches and stopped scopes independently, and document the routing-table boundary.

BREAKING CHANGE: stop and fallback no longer apply globally across
groups. Put mutually exclusive routes in the same group and define
fallback routes in each group that needs its own catch-all.

* fix(dispatch): honor stop on a matching fallback route

Once a fallback matches with stop enabled, skip later routes of the same group without affecting other groups. Cover multiple fallback routes in the group-isolation regression test.

* style(console): pin theme and language controls to the right

Separate utility controls from page actions so narrow screens retain a readable title column and right-aligned actions below. Wrap long headings without letting them push controls out of view.

* style(groups): place creation beside the aligned group count

Keep the new-group action inside the group list at every width and align the label and count on one baseline with a consistent type scale.

* style(groups): align card footers and keep role badges intact

Give long names two lines, show the current role in its own non-wrapping row, and anchor every card footer to the grid-row bottom regardless of optional source metadata.

* style(logs): prevent filter labels and metadata overflow

Keep filter labels on one line and allow long channel, thread and repository identifiers to wrap instead of widening the page.

* style(console): scale the sidebar and hide mobile tab tracks

Narrow the sidebar proportionally while retaining enough room for both locales. Keep mobile navigation swipeable without a visible horizontal scrollbar.

* feat(console): give each group its own routes URL

Resolve the selected group from /admin/groups/{groupId}, validate console paths, and use browser history for back navigation. Keep Groups active and let an active mobile-tab tap return to the list. Scope pending route loads to their group and retain the count beside long headings.

* feat(console): confirm leaving unsaved page work

Guard route changes when an editor or changed order draft is open. Cancel superseded questions and restore the shown history entry when repeated Back or Forward navigation is refused; only completed navigation resets page work.

* feat(console): confirm sign-out from desktop and mobile

Expose sign-out in the mobile topbar when the sidebar is hidden. Both entry points use the in-app confirmation before navigating to the server logout endpoint.

* fix(console): keep topbar tools clear of very narrow headings

Below 360px, place the full-width heading beneath the breadcrumb and utility row so the three top-right buttons cannot overlap it.

* feat(console): prioritize group titles over actions

Place New Route after Reorder in the group bar. Measure available space and remove the reorder label first, then the creation label, before truncating the group title; remeasure on resize, locale and font changes.

* fix(editors): focus the dialog without selecting its name field

Cancel the non-bubbling FocusScope mount event in the capture phase and focus the dialog itself. Keep keyboard navigation working without highlighting the name or opening the touch keyboard automatically.

* perf(console): preserve one instance across admin navigation

Use a fixed page key instead of remounting the whole console for each URL. Refresh each view when shown and isolate overview metrics and logs so page filters cannot leak into the dashboard.

* fix(console-data): discard superseded load responses

Only the latest request may update a list, its error or loading state. Invalidate pending group loads after a save so an older response cannot restore stale configuration during persistent-console navigation.

* fix(routes): serialize writes and reject unloaded route lists

Whole-list saves must start from loaded data and wait for other route writes. Lock switches and actions during saves, recheck deletion after confirmation, and rebuild saved ordering from the newest route objects.

* fix(editors): scope async results and fragment writes to sessions

A completed save or dry run must not close or overwrite a newer editor. Keep fragment state scoped by group, reject writes until the real list is ready, and retain in-flight fragment locks across navigation.

* fix(groups): serialize edits and isolate group detail panels

Prevent overlapping whole-list writes, avoid duplicate ids after rename, and discard delete confirmations prepared on a page that has since been left. Key member and webhook panels by group so local state cannot cross tenants.

* fix(console): omit the empty action row outside overview

Render the refresh-action container only where it has content so narrow layouts do not reserve a blank row after creation controls move into their page bars.

* perf(metrics): send all seven queries in one D1 batch

Avoid seven sequential network round trips and read totals, breakdowns and recent failures in one consistent transaction. Reuse the failed-send statement and row mapping while retaining group scoping.

* fix(admin-api): bypass browser cache locks for live requests

Use no-store on both client requests and admin responses. Personalized live data must not be reused, and one stalled same-URL cache entry must not block later log requests behind the browser cache lock.

* docs(routes): Clarify fallback hints and document group-scoped stop and fallback upgrade behavior
2026-10-17 21:13:20 +08:00

14 KiB

Filter Tutorial

Filters decide which webhook events a route 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 in the configuration guide for the reference table, and Supported Events 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 for every filter type.
  • 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 match.
{
  "type": "event",
  "match": ["push", "pull_request"],
  "exclude": false
}

The route above matches both push and pull_request events.

Pattern Syntax

Every filter type shares the same three pattern forms:

Pattern Meaning
plain text Field filters: exact match. keyword: search anywhere.
* / ? Glob wildcards — * any run, ? one char.
/regular expression/ Compiled as a regular expression (case-insensitive flag).
  • On field filters (event/repo/actor/action/branch), plain text and globs match the whole value; on keyword they search anywhere in the payload.
  • Regexes always search: /^feat/ matches values starting with feat, /feat/ matches anywhere.

Examples:

{ "type": "event", "match": "pull_*" }

Matches pull_request, pull_request_review, pull_request_review_comment, ...

{ "type": "repo", "match": "myorg/*" }
{ "type": "branch", "match": "feature-?" }

Matches feature-x, feature-1, but not feature-xy.

{ "type": "branch", "match": "/^feat/" }

Matches any branch whose name starts with feat.

Tip

Globs and regular expressions are case-insensitive too, and * matches across / in repo names (myorg/* also matches myorg/sub/backend).

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.

{ "type": "event", "match": "release" }

Match several events with an array:

{ "type": "event", "match": ["create", "delete"] }

repo — Repository

Matches the repository full name (owner/name). Case-insensitive.

{ "type": "repo", "match": "myorg/backend" }

Route multiple repositories to one channel:

{ "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.

{ "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. Combine it with event to narrow down a specific lifecycle step:

{
  "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
workflow_job The head_branch the job ran on
check_suite The head_branch of the check suite
deployment The deployment ref (strips refs/heads/)
code_scanning_alert The branch the alert belongs to
{
  "type": "event",
  "match": "push"
},
{
  "type": "branch",
  "match": "main"
}

Fires for pushes to main only. To watch several long-lived branches:

{ "type": "branch", "match": ["main", "develop"] }

Note

branch matching is case-insensitive. Use globs (feature/*) or a //-wrapped regex (/^release-/) for prefix or wildcard-style matching.

keyword — Text in the payload

Matches against the full JSON payload, lowercased. It is the most flexible filter: plain text searches anywhere, */? globs search with wildcards, and //-wrapped patterns are compiled as regular expressions (with the i flag).

{ "type": "keyword", "match": "deploy" }

Fires when the payload contains deploy anywhere. Because the payload is lowercased, this matches Deploy, DEPLOY, etc.

{ "type": "keyword", "match": "*release-*" }
{ "type": "keyword", "match": "/^(fix|hotfix)/" }
{ "type": "keyword", "match": "/release-[0-9]+/" }

Behavior details:

  • Patterns longer than 200 characters are not compiled as glob/regex and fall back to plain matching.
  • A //-wrapped pattern that is not a valid regex matches nothing (the filter stays false) rather than erroring.
  • To search for text that is a glob or regex special character (e.g. v1.2.3), rely on the plain-text form — a pattern without *, ?, or // wrapping matches literally.
  • 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:

{ "type": "keyword", "match": "/wip|draft/", "exclude": true }

Skips events whose payload mentions wip or draft.

field — Any payload field (JSONPath)

Matches an arbitrary field of the webhook payload using a dot-separated path, e.g. pull_request.user.login, repository.private, or check_run.conclusion. Array fields are expanded automatically — the filter matches if any element matches.

{ "type": "field", "path": "pull_request.user.login", "match": "dependabot[bot]" }
{ "type": "field", "path": "labels.name", "match": "bug" }

Operators

Field filters (and every filter type except keyword) accept an op to change how the value is compared. The default eq keeps the classic glob/regex/exact behaviour.

Operator Meaning
eq (default) Equal — globs, regexes and plain text, case-insensitive
ne Not equal (inverse of eq)
contains Value contains the pattern (substring)
startsWith Value starts with the pattern
endsWith Value ends with the pattern
regex Explicit regular expression match
gt / gte Numeric greater-than / greater-or-equal
lt / lte Numeric less-than / less-or-equal
in Value equals any of the listed patterns
exists The field is present (non-null); match is ignored
{ "type": "field", "path": "pull_request.commits", "op": "gt", "match": "1" }
{ "type": "field", "path": "label.name", "op": "startsWith", "match": "area/" }

Grouping (all / any / not)

A route can use a nested ast to combine filters with explicit grouping instead of a flat AND list. The ast node is one of { "all": [...] }, { "any": [...] }, or { "not": {...} }:

{
  "id": "grouped",
  "name": "Grouped",
  "ast": {
    "all": [
      { "type": "event", "match": "pull_request" },
      {
        "any": [
          { "type": "field", "path": "pull_request.user.login", "match": "alice" },
          { "type": "field", "path": "pull_request.user.login", "match": "bob" }
        ]
      }
    ]
  },
  "targets": [{ "channelId": "..." }]
}

When ast is present it takes precedence over filters. The admin console's route editor builds ast visually (all/any/not groups), shows a live explanation of the tree, and can test it against a pasted JSON payload via the Test match panel.

Values, field paths and the test event use searchable dropdowns. Suggestions come from GitHub's and Gitea's webhook definitions — events, the actions of the events the route filters on, common payload paths and their known values — each shown as its English key with a description in the console language; search matches the key first, then the English or Chinese description. Anything outside the list can still be typed and is validated before it is added; only values that can never match are rejected (an event name with spaces, a branch with characters git forbids, invalid regex syntax, a non-number for a comparison operator, …). Repository and actor values stay free-form because custom webhooks may carry any string. Text that is typed but not added with Enter blocks saving, fragment saving and test runs instead of being added or dropped silently. Several values can be typed or pasted at once, separated by commas or new lines; a /regex/ keeps its own commas, and with the matches regex (regex) operator only new lines separate values (a raw pattern such as ^v{1,3} may contain commas). Suggestions follow the operator: the substring operators compare text literally, so a glob suggestion becomes the text it implies (release/* → release/ for starts with, *[bot] → [bot] for ends with), matches regex offers each suggestion as the escaped, anchored pattern it means (^dependabot\[bot\]$, ^release/), and comparison operators get no suggestions. Switching between equals / not equals / in and matches regex rewrites /x/ ↔ x in the values already added — both forms compile to the same regular expression, so the condition keeps matching exactly the same. Other values stay as typed (literal, glob and substring comparisons differ from regular expressions on line breaks and Unicode case folding), and values that can never match under the new operator are flagged. Arrays are expanded along a field path, but a path that ends on an array (e.g. commits.modified) is compared as a whole — match one of its elements with contains; the editor switches to contains when such a suggested path is picked.

Named filter fragments

The route editor can save the current filter tree as a named fragment and insert it into other routes. Fragments are editor-side templates stored in D1 (d1_fragments); inserting a fragment inlines its node into the route's ast, so the matching engine itself never resolves fragment references.

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:

{
  "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:

{
  "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:

{
  "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

  • Wildcards are globs, not regex. repo: "myorg/*" matches any repo under myorg (and myorg/sub/backend), but repo: "myorg/.*" matches literally. Use // wrapping for regex: "/myorg\/.*/".
  • A //-wrapped invalid regex never matches. Unlike plain text, an unwrapped invalid pattern is matched literally — wrap patterns only when they are real regular expressions.
  • An action filter on an action-less event never matches. Check the event has an action field first (see 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.