# Protect branches and tags with rulesets

A ruleset protects matching branches or tags: it can require pull requests,
reviews and passing checks, or block deletion and force pushes. Repository
admins manage rulesets under **Settings → Rulesets**. Organizations and teams
can also define rulesets that apply to their repositories.

## Create a ruleset

1. Open **Settings → Rulesets** and choose **New ruleset**.
2. Under **Basics**, enter a name, choose the target (branches or tags), the
   enforcement and one or more patterns. `*` and `?` are the only wildcards,
   for example `main` or `release/*`.
3. Under **Rules**, turn on the rules you want and fill in their settings
   (approval count, required check names and so on).
4. Under **Bypass actors**, optionally let an organization role or a user skip
   the rules, either always or only when merging pull requests.
5. Save.

Enforcement is one of:

- **Active**: the rules are enforced.
- **Evaluate**: the rules only produce warnings, so you can try them first.
- **Disabled**: the ruleset is kept but does nothing.

From the terminal, `cafe repo ruleset create`, `edit`, `list` and `delete`
manage rulesets, and `cafe repo ruleset effective main` shows the rules that
apply to a branch.

## See which rules apply

**Effective rules**, below the ruleset list, shows every ruleset that applies
to the repository, including those inherited from the
[organization](https://staging.git.cafe/docs/organizations/organization-settings.md#rulesets) or a
[team](https://staging.git.cafe/docs/organizations/teams.md#team-rulesets). Inherited rulesets are edited
where they are defined.

## How rules affect pull requests

Anyone can still open a pull request against a protected branch. Merging
checks every active ruleset that matches the target branch:

- **Require pull request**: changes must arrive through a pull request with the
  required number of approvals. Each reviewer's latest approval or
  change request counts; the author's own review does not. Depending on the
  setting, a new push can make earlier approvals stale.
- **Require status checks**: each named check must pass on the exact commit
  being merged. With strict checks, the branch must also be up to date with
  the target.
- **Require linear history**: merge commits are not allowed; use squash or
  rebase.
- **Code owners**: each changed path needs approval from one of its owners in
  `CODEOWNERS` (looked up in the repository root, `.gitcafe/`, `.github/`, then
  `docs/`, from the target branch). The last matching pattern wins. Owners are
  users or organization teams with write access.
- **Restrict pushes**: only admins, or users with a branch role that allows it,
  can update the branch, including by merging.

The pull request's merge area lists any requirement that is not met.

Required signatures, required deployments and restricted file paths cannot be
satisfied yet: they block matching merges unless a bypass applies.

## How rules affect direct pushes

Every pushed branch or tag update is checked. Creation, deletion and
force-push restrictions apply to matching refs. **Require pull request** blocks
direct pushes to matching branches. Rules that need checks or other evidence
(status checks, linear history, signatures, deployments, file paths) also
reject direct pushes to matching refs unless an **always** bypass applies.
Evaluate-only rulesets never block a push.