# Repository rulesets

`/{owner}/{repo}/settings/rulesets` (the **Rulesets** entry in repository
settings) protects branches and tags. Only repository admins can manage it.

## Rulesets

The first table lists the rulesets defined on this repository: name (with a
**Tags** badge when the ruleset targets tags), enforcement (active, evaluate,
disabled), the ref patterns they match, and how many rules they carry. Click a
name to edit it; the trash icon deletes it after confirmation. **New ruleset**
opens a blank editor.

## Effective rules

Below the table, **Effective rules** shows every ruleset that currently applies
to the repository, including ones inherited from the organization or a team.
Each entry shows its scope, target, enforcement, patterns, and one badge per
rule. When nothing applies, the section says so. Organization rulesets are
managed from the [organization's settings](https://git.cafe/docs/organizations/organization-settings.md) and
team rulesets from the [team page](https://git.cafe/docs/organizations/teams.md); they cannot be edited here.

## Editing a ruleset

The editor at `/{owner}/{repo}/settings/rulesets/{id}` (or `/new`) has:

- **Basics**: name, target (branches or tags), enforcement, and the pattern
  list. **Add pattern** adds a row; `*` and `?` are the only wildcards.
- **Rules**: one card per rule with a toggle. Require pull request, require
  status checks, require deployments, and restrict file paths expose their
  parameters once enabled (approval count, check contexts, environments, path
  patterns and action).
- **Bypass actors**: rows of organization role or user (found by username
  search), each always or pull-request-only.

Direct editor links load the specified ruleset independently of list pagination.
A deleted ruleset or an ID belonging to another repository shows a not-found page.

Submitting validates the fields inline (name, patterns, rule parameters) and
keeps the errors current while you fix them. Leaving the editor with unsaved
changes asks for confirmation; **Cancel** discards without asking. If repository
settings or the ruleset changed while you were editing, the save is rejected.
Reload the list and review the current settings before retrying.

## Pull requests and enforcement

Protected branches accept new pull requests: opening a pull does not change a
branch. Merges in repositories hosted directly in GitCafe enforce every matching
active repository, organization,
and directly granted team ruleset. Evaluate rulesets show warnings; disabled
rulesets do not apply.

Required reviews count each reviewer's latest non-comment, non-dismissed verdict,
exclude the pull's author, and honor the stale-review setting. Required checks
must succeed for the exact commit being merged; one passing result does not
cancel another failing result for the same required check. Strict checks require the
head to contain the current target. Linear-history rules prevent merge commits
on diverged branches while permitting squash and rebase.

Code-owner requirements use CODEOWNERS from the exact target revision, never the
pull's edited version. Locations are checked in this order: `CODEOWNERS`,
`.gitcafe/CODEOWNERS`, `.github/CODEOWNERS`, then `docs/CODEOWNERS`. The last
matching pattern determines the alternative owners for each changed path;
renames cover both paths. Each affected group needs approval on the current head
from a named owner with current repository write access, or a current member of a
named organization team with that access. The pull's author cannot satisfy the
requirement. Unsupported patterns, email owners, oversized files/diffs and
unavailable repository data block the merge instead of ignoring protection.

Actor and organization-role bypasses apply to pull merges in both bypass modes.
They do not grant repository merge access, bypass `restrict_pushes`, or override an outstanding
changes-requested verdict on the current head. Current rules, reviews, checks,
membership and permissions are checked again before merging. If the response is
lost, check the existing merge operation before trying again.

**Some configurable rules cannot currently be satisfied.** Required signatures,
required deployments and restricted-file-path rules block matching merges unless
a permitted bypass applies. GitHub mirror merges are also blocked by strict-check
and code-owner requirements. Automatic source-branch cleanup skips
branches with matching active protection.

With `restrict_pushes`, merging requires repository-admin access or the target
branch's `branch-force-pusher` / `branch-admin` assignment, in addition to normal
repository and credential authority. A delegated credential must satisfy both
its actor's and delegator's authority.

## Direct Git pushes

GitCafe checks every proposed branch or tag update before accepting a push.
Active creation, deletion and force-push restrictions apply to matching refs. `restrict_pushes` requires
repository-admin access or a matching branch assignment; a ruleset bypass does
not replace that authorization. An always bypass can skip other constraints;
a pull-request-only bypass cannot. Delegated credentials require both actors to
qualify for a bypass. Evaluate-only rules do not block pushes.

Required pull requests block direct writes to matching refs. Status checks,
linear history, signatures, deployments and file-path rules cannot currently be
satisfied on direct pushes: matching updates are rejected unless a permitted
bypass applies. Unrelated refs remain usable. Use only supported pattern syntax;
unsupported patterns can cause broader blocking than intended.

Instances without push-policy support reject pushes rather than accept changes
without protection. Ask your instance operator if a push reports that support is
unavailable.