# Rules

> Send threads to Needs you, FYI, or Muted, turn pushes on or off, and move threads to Done or Snoozed by themselves.

Source: https://hush-gh.com/docs/rules

Hush's defaults decide what [needs you](https://hush-gh.com/docs/inbox#what-needs-you). Rules change that for the threads that you choose: a repository that is only FYI for you, a bot to mute, a person whose replies you always want pushed.

## How rules work

- Hush sorts a thread with its defaults first. Then it checks your rules **from top to bottom**. **The first rule that matches wins**; the rules below it do not count for that thread.
- A rule has **conditions** (when) and **effects** (then). All conditions must match. A condition with more than one value matches any of them.
- When you save rules, Hush sorts your stored threads again, so the lists change at once.

A rule can do one or more of these:

| Effect           | JSON                                                             | Does                                                                   |
| ---------------- | ---------------------------------------------------------------- | ---------------------------------------------------------------------- |
| Put it in a list | `"category": "action"`, `"fyi"`, or `"muted"`                    | Needs you, FYI, or Muted.                                              |
| Push or not      | `"push": true` or `false`                                        | In place of the [push settings](https://hush-gh.com/docs/notifications#what-gets-pushed). |
| Move it          | `"triage": "done"`, or `"triage": "snooze"` with `"snoozeHours"` | To Done, or snoozed for 1 to 720 hours.                                |

**Move it** acts when the thread has new activity or when the rule starts to match. If you bring a thread back to the inbox yourself, it stays there until its next activity.

## Make a rule

In **Settings → Inbox → Rules**:

- **New rule** adds an empty rule. **From a template** adds a finished example.
- Or right-click a thread in the inbox and choose **Make a rule…**: the new rule has that thread's repository and type.

Each rule is a card. Give it a name (it shows on the threads it sorts, as “rule: Docs repo is FYI”), add conditions, and choose what it does. You can write the conditions as a [query](https://hush-gh.com/docs/query-language), such as `repo:acme/website type:pr`, or pick them one by one. Turn a rule off with its switch; move, duplicate, or delete it from its buttons.

While you edit, each card shows how many of your stored threads it would catch, and the footer says what would change if you save: “If you save: 4 to FYI, 2 to Muted.” Nothing changes until you choose **Save rules**.

## Conditions

| Query word                     | JSON                      | Matches                                                   |
| ------------------------------ | ------------------------- | --------------------------------------------------------- |
| `repo:acme/*`                  | `"repo": "acme/*"`        | The repository. `*` matches anything.                     |
| `author:dependabot*`           | `"author": "dependabot*"` | Who opened the PR or issue.                               |
| `author:bots` / `-author:bots` | `"bot": true` / `false`   | The author is a bot, or a person.                         |
| `from:alice`                   | `"by": "alice"`           | Who did the newest activity: a comment or a review.       |
| `from:bots` / `-from:bots`     | `"byBot": true` / `false` | The newest activity is by a bot, or by a person.          |
| `label:bug`                    | `"label": ["bug"]`        | Has this label (the exact name, any case).                |
| `type:pr`                      | `"type": ["PullRequest"]` | What it is: pr, issue, ci, release, discussion…           |
| `event:mentioned`              | `"reason": ["mention"]`   | Why GitHub notified you.                                  |
| `needs:review`                 | `"kind": ["review"]`      | What Hush thinks you must do, before your rules.          |
| `in:fyi`                       | `"category": ["fyi"]`     | Where Hush's defaults put it, before your rules.          |
| `is:draft` / `-is:draft`       | `"draft": true` / `false` | A draft PR, or not.                                       |
| `is:open`                      | `"state": ["open"]`       | Open, closed, or merged.                                  |
| words                          | `"text": "login bug"`     | Each word is in the title, the repository, or the author. |

Every value is in the [query language](https://hush-gh.com/docs/query-language) reference. The complete list of JSON conditions:

| JSON key | In the editor | Value | Notes |
| --- | --- | --- | --- |
| `repo` | Repository | text or list of texts; `*` and `?` are wildcards | owner/repo. * matches anything, for example acme/*. |
| `author` | Author | text or list of texts; `*` and `?` are wildcards | The PR or issue author. * matches anything, for example dependabot*. |
| `type` | Type | list of values | Values: `PullRequest`, `Issue`, `CheckSuite`, `Release`, `Discussion`, `Commit`, `RepositoryVulnerabilityAlert`, `RepositoryDependabotAlertsThread` |
| `reason` | Why GitHub notified you | list of values | Values: `approval_requested`, `assign`, `author`, `comment`, `ci_activity`, `invitation`, `manual`, `member_feature_requested`, `mention`, `review_requested`, `security_alert`, `security_advisory_credit`, `state_change`, `subscribed`, `team_mention` |
| `kind` | What Hush thinks you must do | list of values | Values: `review`, `fix_ci`, `address_review`, `resolve_conflict`, `merge`, `reply`, `triage`, `security`, `none`. Before rules. "None" is everything that is FYI by default. |
| `category` | Hush’s default | list of values | Values: `action`, `fyi`. Where the thread goes when no rule matches. |
| `state` | State | list of values | Values: `open`, `closed`, `merged`. Of the pull request or issue. |
| `text` | Words | text | Each word must be in the title, repo, or author. Not case-sensitive. |
| `label` | Has label | list of label names (not wildcards) | Any of these labels (exact names). |
| `bot` | Author is a bot | true or false |  |
| `by` | Latest activity by | text or list of texts; `*` and `?` are wildcards | Who wrote the newest comment or review, for example github-actions or *[bot]. |
| `byBot` | Latest activity by a bot | true or false |  |
| `draft` | Draft PR | true or false |  |

## Examples

Most rules are one line. As queries, with what they do:

| When                           | Then                     |
| ------------------------------ | ------------------------ |
| `repo:acme/website`            | FYI                      |
| `author:dependabot*`           | Muted                    |
| `needs:review is:draft`        | No push                  |
| `type:release repo:sveltejs/*` | Needs you, push          |
| `from:github-actions in:fyi`   | Done                     |
| `type:ci repo:acme/nightly`    | Snooze 12 hours, no push |

The same rules in [settings.json](https://hush-gh.com/docs/settings#rules):

```json settings
{
	"rules": [
		{ "name": "Website is FYI", "when": { "repo": "acme/website" }, "then": { "category": "fyi" } },
		{
			"name": "Mute dependabot",
			"when": { "author": "dependabot*" },
			"then": { "category": "muted" }
		},
		{
			"name": "Quiet reviews on drafts",
			"when": { "kind": ["review"], "draft": true },
			"then": { "push": false }
		},
		{
			"name": "Svelte releases need me",
			"when": { "type": ["Release"], "repo": "sveltejs/*" },
			"then": { "category": "action", "push": true }
		},
		{
			"name": "Bot comments are done",
			"when": { "by": "github-actions", "category": ["fyi"] },
			"then": { "triage": "done" }
		},
		{
			"name": "Nightly CI can wait",
			"when": { "type": ["CheckSuite"], "repo": "acme/nightly" },
			"then": { "triage": "snooze", "snoozeHours": 12, "push": false }
		}
	]
}
```

## Tips

- Put narrow rules above wide ones. A wide rule at the top (such as `repo:acme/*`) catches everything below it.
- Use `in:` and `needs:` to change only part of Hush's sorting: `repo:acme/big-monorepo in:fyi` changes nothing about what needs you there.
- To hear about something without seeing it in Needs you, use `"push": true` with `"category": "fyi"`.
- A rule never sends a thread to GitHub: Muted by a rule stays in Hush. **Mute** in the inbox unsubscribes you on GitHub too.