Skip to content

Branch rules

Require pull requests, approvals, checks and an up-to-date branch, and block force pushes and deletion, per branch pattern.

Updated View as Markdown

Branch rules say what changing a branch takes. A repository has one set of rules, each for a branch name pattern; a branch follows its most specific matching rule (fewest wildcards, then the longest literal part). * matches within one / segment and ** across them: release/* matches release/v2, release/** also matches release/2026/q4.

Rules apply to every way a branch changes: git push, the commit API, creating and deleting branches, and merges. Edit them in the console (the repository’s Settings › Branch rules) or replace the whole set with UpdateBranchRules, which needs git.repositories.updateRules. Send the ETag from GetBranchRules as If-Match; if someone changed the rules since, it’s 412 precondition_failed.

Field Meaning
pattern The branches it covers: main, release/*
requirePullRequest The branch changes only by merging a pull request. Implied by requiredApprovals above 0 or any requiredChecks
requiredApprovals 0–10 approvals from people or bots with git.pulls.approve on the branch, other than the author and anyone who pushed to the pull request’s branch
dismissStaleApprovals Approvals count only on the pull request’s current head commit
requiredChecks Up to 20 { name, reporter }: a check that must be success on the head commit. With reporter (a bot’s bot_… ID or a user’s ID), only that reporter’s result counts
requireUpToDate The pull request’s head contains the branch’s current commit
blockForcePush Pushes that rewrite the branch’s history are refused
blockDeletion The branch can’t be deleted
allowedMergeMethods Narrows the repository’s merge methods for this branch; null keeps the repository’s

A push or commit a rule refuses gets 409 blocked_by_rule with the reason; git push prints it.

Who may push, merge and approve

That’s IAM, not part of the rule. git.repositories.push, git.pulls.merge and git.pulls.approve are checked on the branch, named as the repository’s resource name, / and the branch. For example, to let a bot push to any branch but main merge only through reviewed pull requests approved by release managers:

  • give the bot git.repositories.push on …:gtr_4k2m9x0a7qpe/agent/*;
  • protect main with a rule that has requiredApprovals: 1;
  • give the release managers’ group git.pulls.approve and git.pulls.merge on …:gtr_4k2m9x0a7qpe/main.

…:gtr_4k2m9x0a7qpe/* covers every branch of the repository. A policy on the repository’s resource name alone doesn’t cover its branches, and neither does a deny: deny with …:gtr_4k2m9x0a7qpe/*.

Navigation

Type to search…

↑↓ navigate↵ selectEsc close