# Filter Tutorial Filters decide which webhook events a [route](./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** 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. ```json { "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: ```json { "type": "event", "match": "pull_*" } ``` Matches `pull_request`, `pull_request_review`, `pull_request_review_comment`, ... ```json { "type": "repo", "match": "myorg/*" } ``` ```json { "type": "branch", "match": "feature-?" } ``` Matches `feature-x`, `feature-1`, but not `feature-xy`. ```json { "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. ```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 | | `workflow_job` | The `head_branch` the job ran on | | `check_run` | The `head_branch` of the run's check suite | | `check_suite` | The `head_branch` of the check suite | | `deployment` / `deployment_status` | The deployment ref (`deployment.ref`, strips a leading `refs/heads/`) | | `code_scanning_alert` | The alert's ref, without a leading `refs/heads/` (use `main`, not `refs/heads/main`) | ```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 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). ```json { "type": "keyword", "match": "deploy" } ``` Fires when the payload contains `deploy` anywhere. Because the payload is lowercased, this matches `Deploy`, `DEPLOY`, etc. ```json { "type": "keyword", "match": "*release-*" } ``` ```json { "type": "keyword", "match": "/^(fix|hotfix)/" } ``` ```json { "type": "keyword", "match": "/release-[0-9]+/" } ``` Behavior details: - Patterns longer than 200 characters cannot be compiled as glob/regex; such patterns are rejected when saved. - Globs and regular expressions run on the RE2 engine, whose matching time is linear in the input — no pattern can stall the worker. RE2 syntax has no backreferences (`\1`) or lookaround (`(?=…)`, `(?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: ```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": "field", "path": "pull_request.draft", "match": "true", "exclude": true } ], "targets": [{ "platform": "discord", "channelId": "111111111111111111" }] } ``` The `field` filter reads `pull_request.draft` from the payload; 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" } ], "targets": [{ "platform": "discord", "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\"" } ], "targets": [{ "platform": "discord", "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 is rejected.** The console and API refuse it when saved; a route stored with one before is reported as [unreadable](./routes#unreadable-routes) and its group's deliveries retry until it is fixed. Unlike `//`-wrapped text, an unwrapped 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](../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.