Repository rules

Overview

Repository rules are how you stop the things you do not want to happen from happening at all, rather than finding out afterwards. Branch rules decide who may move a branch and who may merge into it. Push rules decide what a push is allowed to contain — signed commits, a message format, an author-email pattern, a file-size ceiling, a named work item. Commit statuses are how an outside system reports its verdict on a commit back to Gitmoap, so a build result is visible next to the code that produced it.

Both kinds of rule can be set on a repository or on a group, and a group's rules reach every repository beneath it — including repositories in nested groups. That is what makes them worth setting once: protect main on the group that owns forty repositories and all forty are protected, including the ones created next week. Commit statuses are the exception: a status is posted against one commit in one repository, and there is nothing to configure ahead of time.

Quick start

Before you start

How it works

The three rules answer three different questions

A branch rule never inspects a commit, and a push rule never asks who you are. They compose, and a push has to satisfy both, but not at the same moment. The branch rule is settled first, before git writes anything: if the branch you are moving is protected above your level, the push is refused and the objects are never taken. Every push rule is checked afterwards, once the objects have arrived, because each of them has to read the commits or the files they change.

One branch rule applies to a branch, and it is the most specific one

A branch rule targets a pattern rather than a name, and * matches any run of characters — including /, so release/* matches release/v2 and release/2026/q1 alike. When a branch is touched, every rule in force is matched against its name and exactly one wins:

1. an exact match — a pattern with no * in it — beats any pattern with a *;
2. otherwise the pattern with the longest run of literal characters before its first * wins, so release/* beats *;
3. otherwise the longer pattern wins, and if two are still tied, the alphabetically first one.

A branch that matches no pattern is unprotected, and the ordinary access levels apply on their own: Developer to create a branch, and Developer to delete one.

The consequence people trip over: rules do not stack. If a group protects * with allowed_to_push: owner and the repository adds a rule for release/* with allowed_to_push: developer, then a push to release/v3 is checked only against the release/* rule. The stricter rule does not also apply. The one exception is an enforced group rule, and only for its own pattern.

Branch rules inherit whole; push rules inherit field by field

Both walk from the repository up through its parent group, its grandparent and so on to the root. They differ in what they carry up.

A branch rule is inherited as a unit, keyed on the exact pattern text. The nearest scope that defines a pattern owns that pattern completely — every field of it, not just the ones it set. A repository that defines main with allowed_to_push: developer replaces the group's main rule entirely, including its allow_force_push and its allowlists. Patterns that no closer scope defines are inherited as they are, so a repository ends up with the union of its own patterns and every ancestor pattern it did not override.

A push rule set is a flat bag of settings, and each setting is inherited on its own. The nearest scope that sets a field wins for that field, and everything else keeps coming from further up:

Setting a switch to false, or max_file_size_mb to 0, is an override rather than an erasure — it means do not do this, whatever a parent says, and it is how a repository loosens a rule its group set. Sending null for a field is the opposite move: it drops the repository's own value and puts that field back to inheriting.

Nothing stops the walk, so an inherited pattern cannot be switched off from below — clearing it only restores inheritance from the group that set it. To loosen one, set your own pattern on the repository. It replaces the inherited pattern for that field, and a pattern that every message satisfies, such as ^, is as good as none — unless the group's push rules are enforced.

An enforced group rule can only be made stricter beneath

A group's branch rule, or a group's push rules, can be enforced. An enforced rule still reaches every repository beneath the group, but a repository or subgroup can no longer loosen it — only tighten it.

For a branch rule, the nearest rule for a pattern still wins as usual, and then every enforced group rule for that same pattern tightens it:

For push rules, an enforced group's settings hold in every repository beneath it: a check it turns on — reject_unsigned_commits, require_issue_reference, require_closing_issue_reference — stays on, its max_file_size_mb is the most any repository beneath may allow, and its patterns — commit_message_regex, author_email_regex, prohibited_file_names_regex — replace any set beneath.

A change beneath that would loosen an enforced rule is refused with 422 WOULD_WEAKEN_ENFORCED_RULE, and the message names the field: a lower level, a force-push the enforced rule forbids, dropping code-owner approval, an allowlist entry it does not name, a check it turns on switched off, a larger or unlimited file size, or a different pattern. Only a group's rules can be enforced — nothing is beneath a repository to hold to them. This is the same "stricter only" model as enforced approval rules.

What a refused push looks like

Push rules are checked after the objects arrive, because each of them has to read the commits or the files they change. If anything fails, every ref in the push is put back where it was and git prints the whole list:

Nothing lands partially. The push either applies whole or leaves the repository exactly as it was.

How to

See which rules apply to a repository

A repository's branch-rule listing returns the rules the repository itself declares. Ask for the inherited set instead and you get what is actually in force — the repository's own rules merged with every ancestor group's, each item labelled with the scope it came from, so you can tell at a glance which rules you can change here and which you have to go up a level to change.

Push rules read differently at the two levels, and the difference is deliberate. A repository's push rules come back resolved: every setting has a concrete value with inheritance already applied, which is the answer to what will happen to my next push. A group's push rules come back raw — only what that group sets itself, with everything else absent.

Read a single branch rule

Useful when you have a rule id from a listing, an audit entry or a script and want the whole rule including its allowlists.

Protect a branch

Give the pattern and the thresholds. Everything is optional except the pattern: a rule you create with nothing else set requires Maintainer to push and Maintainer to merge, forbids force-push, does not require code-owner approval, and has empty allowlists.

allowed_to_push and allowed_to_merge are floored at Developer — guest and reporter are refused, because a rule that lets a non-member move a branch is a rule that protects nothing.

The two thresholds are independent and are checked on different actions. allowed_to_push governs moving the branch directly — git push, and creating or deleting the branch through Gitmoap. allowed_to_merge governs landing a merge request that targets the branch, and merging never consults allowed_to_push. Setting allowed_to_push: owner with allowed_to_merge: developer is the common shape: nobody pushes to main by hand, but any Developer can land a reviewed merge request into it.

allow_force_push is a property of the rule and not of your level. Left off, a non-fast-forward push to a matching branch is refused for everyone, Owners included.

require_code_owner_approval turns into a check on the merge request rather than on the push: a merge into a matching branch waits for approval from whoever owns the changed files, whether that ownership comes from a CODEOWNERS file or from the service catalog. If nothing claims a changed file, the check fails rather than passing quietly — a rule that requires an owner and finds none has not been satisfied.

Change who can push or merge to a protected branch

Every field of a rule can be changed except its pattern. The pattern is the rule's identity, so moving protection from release/* to releases/* means creating the new rule and deleting the old one.

To let one build agent past a threshold without promoting it, add its id to push_allowlist or merge_allowlist. A team's id works too, and then everyone on the team is let past. A rule permits an action when the caller's level is high enough or the caller — or a team they are on — is on the matching allowlist — so a service account sitting at Developer can push to a branch that requires Owner, and nothing else about it changes. The two lists are independent: being on the push allowlist grants no merge permission. And an allowlist only lifts a caller past the rule; the ordinary level for the action is checked first and still applies, so an account below Developer can neither push to a branch nor delete one, however the allowlists read.

Sending an allowlist replaces it entirely rather than adding to it. Send the full list you want, and send [] to clear one. Each list holds up to 50 entries, they must be distinct, and every entry has to be a real user, service account or team of your organisation — an id that resolves to none of them is refused rather than stored. Deleting a team removes it from every allowlist.

Remove a branch rule

Deleting a branch rule never deletes a branch, and deleting a branch never deletes a rule — a rule outlives the branch it protected, so a branch that is recreated is protected again the moment it exists.

Protect a branch across every repository in a group

A group branch rule has the same shape as a repository one and reaches every repository beneath the group, at any depth. This is the setting worth reaching for first: one main rule on the top-level group is the whole organisation's default, and repositories that genuinely need something different can override that one pattern locally.

A repository and its parent group may both define main, and that is the inheritance model rather than a clash — the nearer rule simply wins. Two rules for the same pattern in the same scope is what is refused.

Enforce a rule for every repository in a group

Send "enforcement": "enforced" when you create or change a group's branch rule, or with a group's push rules. From then on every repository and subgroup beneath keeps the rule at least as strict as the group's. Send "enforcement": "default" to let the scopes beneath decide for themselves again. Either way you need Owner on the group, and so does any later change to an enforced rule, and deleting it.

A repository beneath can still add its own rule for main — to raise the merge level, or to name a service account on an allowlist the group's rule also names — but not one that lowers a level, allows a force-push, or drops code-owner approval. A repository rule written before the group enforced main stays stored and is tightened wherever it is looser.

Review and change a group's branch rules

A group's listing shows what that group declares, never what it inherits from its own parents. To see everything in force for a particular repository, ask that repository for its inherited set.

Remove a group branch rule

Constrain what may be pushed

Push rules are one set of settings per repository, so there is nothing to create — you change the set, and it is created the first time you do. Send only the fields you want to change; the rest keep the values they had.

What each setting refuses:

Each of the three pattern fields is an ordinary regular expression, between 1 and 255 characters, and it has to compile — an invalid one is refused when you save it rather than silently disabling the rule at push time. Send null to clear a pattern and go back to inheriting it.

Those seven are the whole set, and the request body takes nothing else: a field it does not list is refused, so a setting you send is never quietly ignored. The effective rules also name override_group_rules, reject_non_dco_commits, prevent_secret_files, check_author_is_user, reject_unverified_users, prevent_tag_removal, commit_message_reject_regex and branch_name_regex; none of them can be set yet, each always reads as off, and they change no push outcome. Where you want their effect, build it out of the seven: prohibited_file_names_regex keeps a path out of a push, and author_email_regex constrains who may author a commit.

require_issue_reference and require_closing_issue_reference are one check, not two — asking for both gives you the stricter one, and no commit is examined twice. Two things are exempt: merge commits, whose message git writes rather than a person, and tag pushes, because a tag is not where anybody writes a commit message. The commit and file checks still run against any new commits a tag brings with it.

Apply push rules to a whole group

Set the baseline once on the group. Each repository beneath it inherits every field it does not set for itself, so a group can require signed commits everywhere while one repository raises the file-size ceiling and changes nothing else.

Reading a group's push rules gives you that group's own settings and nothing else, which is what you want when you are trying to work out where a value in a repository came from.

Clear push rules and fall back to inheritance

Clearing is how you go back to inheriting. It is not a way to turn rules off — a repository that clears its own set immediately picks up whatever its groups say. To loosen a rule a group sets, override the field instead: send the switch as false, max_file_size_mb as 0, or your own pattern in place of the inherited one. Clearing is idempotent: clearing a set that was never created succeeds and changes nothing.

Report a check result on a commit

An external system — a build server, a scanner, a deployment tool — reports its verdict against a commit and a context. The context is the check's name, and it is what makes the report replaceable: post ci/jenkins as pending when the build starts and again as success when it finishes, and the second post overwrites the first rather than adding a row. Contexts are yours to choose; a path-like name such as ci/jenkins or security/scan keeps a commit's list readable when several systems report on it.

Give target_url whenever you have somewhere to send a person — it is what turns a red mark into a link to the failing log.

The commit is named by its full 40-character hash — a short hash is refused. Gitmoap does not check that the commit exists: a status posted against a hash that never arrives is stored, and surfaces only if something asks for that exact hash. That is what keeps a build agent reporting slightly ahead of a push from failing.

Read the checks on a commit

The listing returns every status on the commit, one per context, newest values in place — plus a combined state, which is the single answer for a commit that several systems report on. It is the worst state present, folded into three values: any failure or error makes it failure, otherwise anything pending or running makes it pending, and only when every context is success is the combined state success. A combined state is never error or running — read the individual contexts to tell an errored check from a failed one. A commit nobody has reported on comes back with an empty list and no combined state at all, which is different from a green one.

A commit status is a report and not a gate. Nothing refuses a merge because a context is red. The merge checks are a separate list: draft state, the branch rule's merge threshold, code-owner approval, the approval rules, a rejected review, unresolved discussion threads, an unmerged merge request below this one in a stack and — where the repository requires them — a linked work item, its Proof of Done criteria, and every pipeline that applies to the merge request's head having passed (Merge request settings).

Reference

Branch rules — repository

Branch rules — group

Push rules

Commit statuses

Limits

Branch rules are capped per scope, counted separately for each repository and each group, and the ceiling moves with your plan:

One over the ceiling is refused with 429 TOO_MANY_REQUESTS and the message branch rule quota reached (max N), naming the limit in force. Nothing is partially created — the rule does not exist, and no counter has moved. The cap is per scope rather than per repository tree, so a repository at its own ceiling still inherits everything its groups define.

Reaching the ceiling usually means the patterns are too specific. One release/* rule replaces a rule per release branch and keeps working for branches nobody has cut yet. Otherwise, delete a rule you no longer need, or move a rule that several repositories share up to the group they have in common — a group rule costs one slot in the group, not one in each repository.

Allowlists: 50 entries each, per rule, for pushing and for merging separately. Going over is refused with 400 BAD_REQUEST rather than 429, because it is the shape of your request rather than a limit on your plan. If a rule needs more than 50 named identities, the threshold is the wrong tool — lower allowed_to_push to the level those people already have.

Commit statuses: distinct commit-and-context pairs per repository, and this one does move with your plan:

The count is repository-wide rather than per commit, and it only ever grows — statuses are not deleted, so a slot taken by an old commit stays taken. Re-reporting a context you have already used on the same commit is an update in place and takes no further slot, so a build that reports ci/jenkins as pending, then running, then success on one commit consumes one. At the cap a new report is refused with 429 TOO_MANY_REQUESTS and the message commit status quota reached (max N); the status is not written. Use a stable context name per check and let the state carry the change, and post statuses only for the checks somebody reads — a reporting system that mints a fresh context per attempt burns the budget in an afternoon.

Push rules have no count cap — a repository or group has one set, not a collection. The bound that bites is per pattern: each of the three pattern fields is at most 255 characters.

To raise the branch-rule or commit-status ceiling, change your plan, or ask for an increase on the group that owns the repository. See Billing and plans.

Troubleshooting

Examples

Protect main for a whole organisation, and let the release automation move release branches:

Nobody pushes to main by hand, any Developer can land a reviewed merge request into it, and the owners of the changed files have to approve first. Then, on the repository that cuts releases:

The id is the release service account. It sits at Developer and stays there; the allowlist is what lets it push to release/* without giving it Maintainer over everything else.

A conventional-commits baseline for a group, with a file-size ceiling and the paths a credential usually arrives under kept out:

Every repository beneath the group inherits all four. A repository that vendors large binaries raises its own ceiling with {"max_file_size_mb": 200} and keeps the other three exactly as they are. A repository that has to accept one of those paths sends its own narrower prohibited_file_names_regex rather than clearing the field, because clearing it only goes back to inheriting the group's.

FAQ

Related