| 1 | --- |
| 2 | title: Rules |
| 3 | description: Rulesets decide what may happen to a repository's branches and tags, and what a pull request needs before it merges. |
| 4 | --- |
| 5 | |
| 6 | A **ruleset** says what may happen to some of a repository's branches or |
| 7 | tags, and what a pull request into them needs before it merges. Every push, |
| 8 | every merge, and every branch renamed or commit made through g1t is checked |
| 9 | against the rulesets that cover it. Only the people, teams, tokens or g1t |
| 10 | processes that a ruleset lists as able to bypass it are let through. |
| 11 | |
| 12 | A ruleset belongs to a repository, or to a workspace. A workspace's ruleset |
| 13 | holds in every repository it selects. When several rulesets cover a branch, |
| 14 | all of their rules hold, so the strictest one wins. |
| 15 | |
| 16 | ## What a ruleset has |
| 17 | |
| 18 | | Part | What it is | |
| 19 | | --- | --- | |
| 20 | | Name | What people call it, up to 100 characters. | |
| 21 | | Enforcement | `active`: its rules hold. `evaluate`: nothing is refused, and every push or merge it would have refused is recorded (see [Insights](#insights)). `disabled`: kept, but not checked. | |
| 22 | | Target | `branch` or `tag`. | |
| 23 | | Branches or tags | `include` and `exclude` patterns. A name is covered when it matches an include pattern and no exclude pattern. | |
| 24 | | Repositories | A workspace's ruleset only: which of its repositories it holds in. | |
| 25 | | Bypass list | Who these rules do not hold for. Nobody is on it unless listed. | |
| 26 | | Rules | What holds, each with its parameters. | |
| 27 | |
| 28 | ### Patterns |
| 29 | |
| 30 | Branch, tag and repository names are matched with fnmatch patterns: |
| 31 | |
| 32 | | Pattern | Matches | |
| 33 | | --- | --- | |
| 34 | | `~DEFAULT_BRANCH` | The repository's default branch, whatever it is called now. | |
| 35 | | `~ALL` | Every branch, tag or repository. | |
| 36 | | `release/*` | `release/1.x`, but not `release/1.x/hotfix`: `*` stays within one segment. | |
| 37 | | `release/**` | Everything under `release/`. | |
| 38 | | `v[0-9]*` | `v1`, `v2.0.1`. `[...]` matches one character of a set; `[!...]` one not in it. | |
| 39 | |
| 40 | A pattern written as a full ref, such as `refs/heads/main`, works too. An |
| 41 | empty include list covers nothing. |
| 42 | |
| 43 | File path patterns in rules work the same way, with one addition: a |
| 44 | pattern without a `/`, such as `*.exe` or `CODEOWNERS`, matches a file of |
| 45 | that name in any directory. A pattern ending in `/` matches everything |
| 46 | under it. |
| 47 | |
| 48 | ### Repositories a workspace ruleset holds in |
| 49 | |
| 50 | | Condition | What it does | |
| 51 | | --- | --- | |
| 52 | | `include`, `exclude` | Repository name patterns, ignoring case. `~ALL` is every repository. | |
| 53 | | `visibility` | `any`, `public` or `private`. | |
| 54 | | `topics` | Only repositories with at least one of these [topics](/guides/managing-repositories/). Empty means any. | |
| 55 | |
| 56 | ## Create a ruleset |
| 57 | |
| 58 | You need the Admin [role](/guides/access-and-roles/) for a |
| 59 | repository's ruleset. For a workspace's, you need to be an owner. |
| 60 | |
| 61 | 1. Open the repository's **Settings → Rules**, or the workspace's |
| 62 | **Settings → Rules**. |
| 63 | 2. Choose **New ruleset**. |
| 64 | 3. Name it, choose **Branches** or **Tags**, and set which names it covers. |
| 65 | **Default branch** and **All branches** are a click away. |
| 66 | 4. Choose its enforcement. To try it without refusing anything, choose |
| 67 | **Evaluate** and watch Insights. |
| 68 | 5. Add people, teams, roles, tokens or g1t who may bypass it, if anyone. |
| 69 | 6. Choose **Add a rule** for each rule, and set its parameters. |
| 70 | 7. Choose **Create ruleset**. |
| 71 | |
| 72 | **Export JSON** downloads a ruleset. **Import JSON** fills the form from a |
| 73 | ruleset file, so one ruleset can be copied to other repositories or |
| 74 | workspaces. The file is the ruleset as the [API](#from-the-api) shows it. |
| 75 | |
| 76 | ## The rules that hold for a branch |
| 77 | |
| 78 | Under **Settings → Rules**, **What holds for a branch** lists every rule of |
| 79 | every ruleset that covers a branch, the repository's and its workspace's, |
| 80 | active ones first. For each ruleset it also shows who may bypass it. To see |
| 81 | a tag's rules, put `?tag=v1.0` in the address. |
| 82 | |
| 83 | The **Rules** box on a pull request lists each rule of its base branch it |
| 84 | does not meet yet. For each one it shows which ruleset it comes from and |
| 85 | what to do about it. |
| 86 | |
| 87 | ## Who may bypass |
| 88 | |
| 89 | | Kind | `value` | Who | |
| 90 | | --- | --- | --- | |
| 91 | | `role` | `write`, `maintain`, `admin` (that role or higher), or `owner` | People with that role on the repository, or the workspace's owners. | |
| 92 | | `team` | `team` or `workspace/team` | The team's people, child teams included. | |
| 93 | | `user` | A username | One person. | |
| 94 | | `token` | A token's id, or `workspace` | That access token, or any of the workspace's own tokens. | |
| 95 | | `g1t` | None | g1t acting on its own, such as the merge queue and security updates. | |
| 96 | |
| 97 | Each entry has a `mode`: |
| 98 | |
| 99 | - `always`: pushes and merges both go through. |
| 100 | - `pull_requests`: only merges go through. Their pushes follow the rules. |
| 101 | |
| 102 | When a person who may bypass merges a pull request that does not meet the |
| 103 | rules, the merge box offers **Bypass the rules**. Through the API, pass |
| 104 | `bypass_rules`. A push from someone on the bypass list goes through by |
| 105 | itself, since git has no box to tick. Every bypass is recorded in |
| 106 | [Insights](#insights). |
| 107 | |
| 108 | ## Rules |
| 109 | |
| 110 | Each rule has a `type` and `parameters`. A parameter you leave out takes its |
| 111 | default. |
| 112 | |
| 113 | ### Branches and tags |
| 114 | |
| 115 | | Rule | `type` | What it does | Parameters | |
| 116 | | --- | --- | --- | --- | |
| 117 | | Restrict creations | `creation` | Only people on the bypass list create matching branches or tags. | None | |
| 118 | | Restrict updates | `update` | Only people on the bypass list push to matching branches or tags. This covers merges too. | None | |
| 119 | | Restrict deletions | `deletion` | Only people on the bypass list delete them. | None | |
| 120 | | Block force pushes | `non_fast_forward` | A push must add to the branch's history, never rewrite it. | None | |
| 121 | | Branch name pattern | `branch_name_pattern` | New branches must be named as it says. | [Pattern](#pattern-rules) | |
| 122 | | Tag name pattern | `tag_name_pattern` | New tags must be named as it says. | [Pattern](#pattern-rules) | |
| 123 | |
| 124 | ### Pull requests and checks |
| 125 | |
| 126 | | Rule | `type` | What it does | |
| 127 | | --- | --- | --- | |
| 128 | | Require a pull request before merging | `pull_request` | Pushes straight to the branch are refused. A pull request into it needs what the parameters say. | |
| 129 | | Require status checks to pass | `required_status_checks` | These checks must pass on a pull request's head before it merges. | |
| 130 | | Require the merge queue | `merge_queue` | Merging into the default branch adds the pull request to the [merge queue](/guides/merge-queue/), with these settings. On other branches it merges directly. | |
| 131 | | Require deployments to succeed | `required_deployments` | A pull request's head must have deployed successfully to these environments: on g1t.page, or anywhere it was reported. | |
| 132 | |
| 133 | `pull_request` parameters: |
| 134 | |
| 135 | | Parameter | Default | What it does | |
| 136 | | --- | --- | --- | |
| 137 | | `required_approvals` | `0` | Approving reviews needed, 0 to 10. A reviewer who has since asked for changes blocks the merge. Nobody approves their own pull request. | |
| 138 | | `dismiss_stale_reviews_on_push` | `false` | Approvals given before the latest push no longer count. | |
| 139 | | `require_code_owner_review` | `false` | The [code owners](/guides/codeowners/) of every file it changes must approve. | |
| 140 | | `require_last_push_approval` | `false` | Someone other than whoever pushed last must approve after that push. | |
| 141 | | `allowed_merge_methods` | All | The [methods](/guides/pull-requests/#merge-methods) a pull request into the branch may merge by: `merge`, `squash`, `rebase` and `fast_forward`. Within those the repository allows: the merge button offers only methods both allow, and a merge by any other is refused. Where several rulesets set it, a method must be in every list. | |
| 142 | | `allow_direct_pushes` | `false` | Pull requests need what this rule says, but pushes straight to the branch are still allowed. Only the ruleset made from branch protection that did not require pull requests has this on. | |
| 143 | |
| 144 | `required_status_checks` parameters: |
| 145 | |
| 146 | | Parameter | Default | What it does | |
| 147 | | --- | --- | --- | |
| 148 | | `checks` | None | Each check has a `context`, such as `CI` (a workflow's name) or `g1t / deploy`, and an optional `integration`: `actions`, `deployments`, `security`, `g1t` or `api` (a status or [check run](/guides/checks/) reported through the API). A check with an `integration` counts only when that integration reported it, so a workflow cannot stand in for a deployment. A check is met by a status or a check run of its name alike. | |
| 149 | | `strict` | `false` | The pull request must contain the branch's latest commits, so what merges is exactly what was checked. | |
| 150 | | `paths` | Always | The checks are required only when the pull request changes a file matching one of these patterns. | |
| 151 | | `allow_bypass_on_merge` | `false` | Someone who may merge can merge past checks that have not passed by ticking **Bypass the required checks**. | |
| 152 | |
| 153 | `merge_queue` parameters: `max_entries_to_build` (pull requests tested at |
| 154 | once, 1 to 20, default 4), `min_entries_to_merge` and |
| 155 | `min_entries_wait_minutes` (the smallest batch to start, and how long the |
| 156 | oldest entry waits for it to fill; default 1 and 0), |
| 157 | `check_response_timeout_minutes` (how long a batch's checks may take before |
| 158 | it is tested again, 5 to 360, default 45) and `merge_method`. When several |
| 159 | rulesets set a queue, the queue uses the smallest batch size and timeout |
| 160 | and the longest wait among them. |
| 161 | |
| 162 | `required_deployments` takes `environments`. `preview` is a pull request's |
| 163 | [preview deployment](/guides/deployments/). A project's slug is that |
| 164 | project's deployment, when a repository has several. Any other name is an |
| 165 | environment [deployments are reported to](/guides/deployments-api/), from |
| 166 | any CI or by a g1t Actions job with an `environment:`: a successful |
| 167 | `deploy / <environment>` check on the head meets it, such as |
| 168 | `deploy / staging` for `staging`. Names are matched without regard to case. |
| 169 | |
| 170 | ### Commits |
| 171 | |
| 172 | | Rule | `type` | What it does | |
| 173 | | --- | --- | --- | |
| 174 | | Require linear history | `required_linear_history` | No merge commits: a push that adds one is refused, and a pull request into the branch merges by `squash`, `rebase` or `fast_forward`, never `merge`. Update a pull request's branch by rebasing, or let it be squashed. | |
| 175 | | Require signed commits | `required_signatures` | Every commit carries a signature g1t verifies. | |
| 176 | | Commit message pattern | `commit_message_pattern` | Every commit message must match, or must not. | |
| 177 | | Commit author email pattern | `commit_author_email_pattern` | Every author address must match, or must not. | |
| 178 | | Committer email pattern | `committer_email_pattern` | Every committer address must match, or must not. | |
| 179 | |
| 180 | These hold for the commits a push adds and for the commits a pull request |
| 181 | would land when it merges. |
| 182 | |
| 183 | **Signed commits.** g1t verifies SSH signatures made with an ed25519 key: |
| 184 | |
| 185 | ```sh |
| 186 | git config gpg.format ssh |
| 187 | git config user.signingkey ~/.ssh/id_ed25519.pub |
| 188 | git commit -S -m "Add rules" |
| 189 | ``` |
| 190 | |
| 191 | A signature counts as verified when it is valid over the commit and the key |
| 192 | is one of the [SSH keys](/guides/authentication/) on the g1t account that |
| 193 | owns the committer's verified email address. GPG signatures, and SSH |
| 194 | signatures made with RSA or ECDSA keys, are reported as not verified yet. |
| 195 | Commits g1t makes itself, such as catching a pull request up and web edits, |
| 196 | are not signed. So with this rule on a branch, bring pull requests up to |
| 197 | date with a signed rebase of your own. |
| 198 | |
| 199 | ### Pattern rules |
| 200 | |
| 201 | | Parameter | What it does | |
| 202 | | --- | --- | |
| 203 | | `operator` | `starts_with`, `ends_with`, `contains` or `regex`. | |
| 204 | | `pattern` | The text, or the regular expression. | |
| 205 | | `negate` | The text must not match. | |
| 206 | | `name` | What the rule is called in refusals, such as `Conventional commits`. | |
| 207 | |
| 208 | Regular expressions run on a linear-time engine. A pattern can never make a |
| 209 | push slow, and look-around and back-references are not supported. For |
| 210 | example, conventional commits: |
| 211 | |
| 212 | ```json |
| 213 | { "type": "commit_message_pattern", "parameters": { "name": "Conventional commits", "operator": "regex", "pattern": "^(feat|fix|docs|chore)(\\(.+\\))?: " } } |
| 214 | ``` |
| 215 | |
| 216 | ### Files |
| 217 | |
| 218 | | Rule | `type` | What it does | Parameters | |
| 219 | | --- | --- | --- | --- | |
| 220 | | Restrict file paths | `file_path_restriction` | Changes to matching paths are refused, deletions included. | `restricted_file_paths` | |
| 221 | | Restrict file extensions | `file_extension_restriction` | Files with these extensions may not be added or changed. | `restricted_file_extensions`, such as `.exe` | |
| 222 | | Restrict file size | `max_file_size` | No file larger than this. | `max_file_size_mb`, 1 to 100 | |
| 223 | | Restrict file path length | `max_file_path_length` | No path longer than this. | `max_file_path_length` | |
| 224 | | Restrict files changed | `max_files_changed` | A commit may change at most this many files. | `max_files` | |
| 225 | | Block pushes that add secrets | `secret_scanning` | Every push to the branch is scanned by [push protection](/guides/security/secret-protection/). A push too large to scan is refused rather than let through unscanned. | None | |
| 226 | |
| 227 | ### Review and timing |
| 228 | |
| 229 | | Rule | `type` | What it does | Parameters | |
| 230 | | --- | --- | --- | --- | |
| 231 | | Review for sensitive paths | `path_review` | A pull request that changes a matching file needs approvals from people since its latest push, from `team` when one is named. | `paths`, `required_approvals`, `team` | |
| 232 | | Merge window | `merge_window` | When pull requests may merge into the branch. | See below | |
| 233 | |
| 234 | `merge_window` parameters: |
| 235 | |
| 236 | | Parameter | What it does | |
| 237 | | --- | --- | |
| 238 | | `time_zone` | A fixed offset from UTC, such as `+02:00` or `-05:00`, or `UTC`. Daylight saving time is not applied. | |
| 239 | | `windows` | Weekly hours when merging is open: each has `days` (`mon` to `sun`), `start` and `end` as `HH:MM`. An `end` before its `start` runs past midnight. With none, merging is open whenever no freeze covers the moment. | |
| 240 | | `freezes` | Periods when merging waits, each with `start`, `end` (RFC 3339) and a `reason`. A freeze without an `end` lasts until you remove it. Use one during an incident. **Freeze now, until lifted** adds one. | |
| 241 | | `exceptions` | Periods when merging is open whatever the windows and freezes say, such as a hotfix. | |
| 242 | |
| 243 | A refusal outside the window says when it next opens. |
| 244 | |
| 245 | ## Evaluate mode |
| 246 | |
| 247 | A ruleset in `evaluate` refuses nothing. Every push and merge it would have |
| 248 | refused is recorded as **Would block** in Insights. On a pull request, the |
| 249 | merge box lists what it would refuse under **Rulesets in evaluate would |
| 250 | refuse it**. Turn a ruleset to **Active** once Insights shows it refusing |
| 251 | only what it should. |
| 252 | |
| 253 | ## Insights |
| 254 | |
| 255 | **Settings → Rules → Insights** lists how the rules judged each push, merge, |
| 256 | branch creation, deletion, rename and commit made on the site, newest first. |
| 257 | Each entry shows the ruleset, the ref, who made the change, and every rule |
| 258 | broken with the reason. Totals cover |
| 259 | the last 30 days: **Passed**, **Blocked** (refused by an active ruleset), |
| 260 | **Would block** and **Bypassed**, with the rules broken most. A workspace's |
| 261 | Insights covers all of its repositories. Evaluations are kept for 90 days. |
| 262 | |
| 263 | Changing a ruleset is recorded in the workspace's |
| 264 | [audit log](/guides/audit-log/) and sent to webhooks as `ruleset.created`, |
| 265 | `ruleset.updated` or `ruleset.deleted`. A workspace's ruleset events go to |
| 266 | the workspace's webhooks. |
| 267 | |
| 268 | ## Where rules are checked |
| 269 | |
| 270 | | Change | What happens | |
| 271 | | --- | --- | |
| 272 | | `git push` | The rules of every branch and tag the push changes are checked before anything is stored. A refused push changes nothing, and git prints why. | |
| 273 | | Merging a pull request | The merge button, the API, MCP, auto-merge, g1t's own merges and the merge queue all check the same rules. | |
| 274 | | Renaming a branch | Covered as deleting the old name and creating the new one. | |
| 275 | | A file committed on the site | Covered as a push of that commit to its new branch. | |
| 276 | | Bringing a pull request up to date | Covered as a push of the merge commit to its branch. | |
| 277 | |
| 278 | A refused push looks like this: |
| 279 | |
| 280 | ```text |
| 281 | remote: |
| 282 | remote: error: rules for refs/heads/main declined this push: |
| 283 | remote: - Changes to main must be made through a pull request. [ruleset "Protect main", pull_request] |
| 284 | remote: Push a branch, open a pull request into main, and merge it. |
| 285 | remote: See the rules that hold for it: https://g1t.sh/acme/web/settings/rules?branch=main |
| 286 | remote: |
| 287 | ! [remote rejected] main -> main (declined by ruleset "Protect main" (pull_request)) |
| 288 | ``` |
| 289 | |
| 290 | A pull request's fork has no rules of its own. |
| 291 | What it brings is checked against the base branch's rules when it merges. |
| 292 | |
| 293 | ## Rulesets and branch protection |
| 294 | |
| 295 | Before rulesets, a repository had one set of protection settings for its |
| 296 | default branch. Each repository's settings became a ruleset named |
| 297 | **Default branch protection**, targeting `~DEFAULT_BRANCH` and holding |
| 298 | exactly what they held: |
| 299 | |
| 300 | | Setting | Becomes | |
| 301 | | --- | --- | |
| 302 | | Require a pull request to change the default branch | `pull_request` | |
| 303 | | Required approvals, require review from code owners | `pull_request`'s `required_approvals`, `require_code_owner_review` | |
| 304 | | Required status checks, require branches to be up to date, allow bypassing required checks | `required_status_checks`'s `checks`, `strict`, `allow_bypass_on_merge` | |
| 305 | | Merge through a queue | `merge_queue` | |
| 306 | |
| 307 | Where approvals or code owners were required but pushes were not refused, |
| 308 | the `pull_request` rule has `allow_direct_pushes` on, so pushes still go |
| 309 | through as before. |
| 310 | |
| 311 | Pull requests into other branches used to need nothing. Now they need what |
| 312 | the rulesets covering their base ask for. With only the migrated ruleset, |
| 313 | that is still nothing. |
| 314 | |
| 315 | [`update_repo_settings`](/reference/api/repositories/update-repo-settings/) |
| 316 | still takes the old fields and writes them to the **Default branch |
| 317 | protection** ruleset, creating it when needed. Rules only rulesets have |
| 318 | stay as they are. [`get_repo_settings`](/reference/api/repositories/get-repo-settings/) |
| 319 | returns the default branch's protection as all of its rulesets stack. The |
| 320 | `protected` field of [`update_repo`](/reference/api/repositories/update-repo/) |
| 321 | turns the ruleset's pull request requirement on or off. |
| 322 | |
| 323 | ## From the API |
| 324 | |
| 325 | | Route | MCP | What it does | |
| 326 | | --- | --- | --- | |
| 327 | | `GET /repos/{owner}/{name}/rulesets` | `repository` `list_rulesets` | A repository's rulesets; `include_parents` adds the workspace's that hold in it. | |
| 328 | | `POST /repos/{owner}/{name}/rulesets` | `repository` `create_ruleset` | Create one. | |
| 329 | | `GET /repos/{owner}/{name}/rulesets/{id}` | `repository` `get_ruleset` | One ruleset. | |
| 330 | | `PUT /repos/{owner}/{name}/rulesets/{id}` | `repository` `update_ruleset` | Change one. Fields you leave out stay as they are. | |
| 331 | | `DELETE /repos/{owner}/{name}/rulesets/{id}` | `repository` `delete_ruleset` | Delete one. | |
| 332 | | `GET /repos/{owner}/{name}/rules/branches/{branch}` | `repository` `branch_rules` | Every rule that holds for a branch (`?target=tag` for a tag). Encode slashes: `release%2F1.x`. | |
| 333 | | `GET /repos/{owner}/{name}/rules/evaluations` | `repository` `rule_evaluations` | Evaluations and insights; `ruleset_id`, `verdict`, `problems_only`, `before`, `limit`. | |
| 334 | | `/workspaces/{workspace}/rulesets` and `/workspaces/{workspace}/rules/evaluations` | `workspace` `list_rulesets` and the rest | The same for a workspace. | |
| 335 | |
| 336 | The body of a create or update is the ruleset. Under a repository's |
| 337 | address, `name` already names the repository, so the ruleset's name is |
| 338 | `ruleset_name`. A file exported from the site, which says `name`, is read as |
| 339 | it is. |
| 340 | |
| 341 | ```sh |
| 342 | curl -X POST https://api.g1t.sh/repos/acme/web/rulesets \ |
| 343 | -H "Authorization: Bearer $G1T_TOKEN" \ |
| 344 | -H "Content-Type: application/json" \ |
| 345 | -d '{ |
| 346 | "ruleset_name": "Protect main", |
| 347 | "conditions": { "ref_name": { "include": ["~DEFAULT_BRANCH"] } }, |
| 348 | "bypass_actors": [{ "kind": "role", "value": "admin", "mode": "pull_requests" }], |
| 349 | "rules": [ |
| 350 | { "type": "deletion" }, |
| 351 | { "type": "non_fast_forward" }, |
| 352 | { "type": "pull_request", "parameters": { "required_approvals": 1, "dismiss_stale_reviews_on_push": true } }, |
| 353 | { "type": "required_status_checks", "parameters": { "checks": [{ "context": "CI", "integration": "actions" }], "strict": true } } |
| 354 | ] |
| 355 | }' |
| 356 | ``` |
| 357 | |
| 358 | Reading rulesets takes the `repo:read` or `workspace:read` |
| 359 | [scope](/guides/authentication/). Changing them takes `repo:admin` or |
| 360 | `workspace:admin`, since it changes what everyone may do. |
| 361 | [`merge_pull_request`](/reference/api/pull-requests/merge-pull-request/) |
| 362 | takes `bypass_rules`. [`get_pull_request`](/reference/api/pull-requests/get-pull-request/) |
| 363 | returns `rules`: what is `unmet`, what you may bypass (`bypassable`), |
| 364 | and what rulesets in evaluate would refuse (`evaluate`). |
| 365 | |
| 366 | Every operation is in the [API reference](/reference/api/rules/list-repo-rulesets/). |