# Rules

> Automation that places cards on the board when something happens on GitHub.

A rule watches what GitHub tells the board, and places cards when something matches. Rules only ever add cards: they never move or remove what people placed.

![The rules panel beside a board: two rules, one placing pull requests beside the issues they mention and one adding new bugs to a section, each with a switch to pause it.](https://tack.social/_astro/rules-light.CpeBbMux_2qHoDd.webp)

Choose **Rules** in the top bar (“Rules: automation that places cards”). The badge counts the rules that are on.

## The two kinds

**Pull requests for cards**: “When a pull request mentions a card on this board, place it beside that card.” Tick **Only pull requests that close the card (“Fixes #12”)** to only place pull requests that say they close it.

- Mentions are `#12`, `owner/repo#12` or a link to the issue, in the pull request’s title or description (not in code blocks).
- Closing means a keyword before the mention: close, closes, closed, fix, fixes, fixed, resolve, resolves or resolved.
- The pull request lands in free space beside the first card it mentions, to the right if there’s room.

**Search matches**: “When an item starts matching this search, add it to “Section”.” Write a search and choose a section. An item starts matching when it’s opened, or labelled or edited so that it matches. The composer counts what matches now, and helps with a search in plain words as list settings do.

- The item goes in the first free spot inside the section, or below it if the section is full.
- Rules check the search themselves, so they understand a subset of GitHub’s search: see [Search syntax](https://tack.social/widgets/search-syntax.md#rules). A rule needs a `repo:owner/name`.

Start from **Pull requests beside their issues** or **New matches into a section** if the board has no rules yet, or choose **New rule**, which starts from a ready-made search and a section no rule uses yet. The composer says what the rule will do as you write it, or what’s wrong, including when a rule already does the same.

**Rules or an inbox?** Both bring search matches into a section. A rule places them straight in; an [inbox](https://tack.social/automation/inboxes.md) queues them in a tray for people to sort first. The composer offers **Make “Section” an inbox instead**, and an inbox’s editor has **Place new matches straight in**, which adds the rule for you.

## What rules will and won’t do

- Rules run when **GitHub sends the board a webhook**, so they only see repositories with the [GitHub App installed](https://tack.social/self-hosting/repositories.md).
- They run with the app’s access, and only place items from **repositories already on the board** (with at least one card), or **chosen for it** when it was made from a template.
- They never place an item that’s already on the board, and **each rule places an item at most once**, even if someone removes it afterwards.
- Cards a rule places can’t be undone, since nobody placed them; remove them like any card.
- Cards a rule placed remember it, and are marked if they stop matching. See [Where cards come from](https://tack.social/automation/provenance.md).

## Pausing and activity

Each rule has a switch to pause it, says how many cards it’s placed and when, and can be deleted (with Undo).

To pause every rule at once for a live session, choose **Pause all** at the top of the panel (or **Pause rules for this session** in the Facilitate menu). While they’re paused, the top bar’s Rules button shows a pause mark and how many updates are waiting; nothing is lost, and **Resume** places what they would have placed, in order. Rules hold up to the last 200 updates while paused.

**Recent activity** lists what rules did, newest first: “Placed #431 beside #412”, “Added #440 to “Bugs””, “Couldn’t find room for #441”. Click one to find the card. When a rule places a card while you’re on the board, a toast says so and names the rule (“Placed #431 beside #412, by “Pull requests beside their issues””), with **Show** to find the card and **Remove** to take it off the board (which you can undo).