Branch Protection Rule

Definition of a Branch Protection Rule, the following properties are supported:

Key	Value	Description	Notes
pattern	string	Pattern to match branches that shall be protected by this branch protection rule	Pattern follows fnmatch syntax, see doc@GitHub for more info
requires_pull_request	boolean	If enabled, requires a pull request before merging. All commits must be made to a non-protected branch and submitted via a pull request before they can be merged into matching branches
required_approving_review_count	integer or null	If specified, pull requests targeting a matching branch require a number of approvals and no changes requested before they can be merged.	Only taken into account when requires_pull_request is enabled, should be set to null when requires_pull_request is disabled
dismisses_stale_reviews	boolean	If enabled, dismiss approved reviews automatically when a new commit is pushed	Only taken into account when requires_pull_request is enabled
requires_code_owner_reviews	boolean	If enabled, require an approved review in pull requests including files with a designated code owner	Only taken into account when requires_pull_request is enabled
restricts_review_dismissals	boolean	If enabled, only allowed actors can dismiss reviews on pull requests	Only taken into account when requires_pull_request is enabled
review_dismissal_allowances	list[Actor]	List of actors that are permitted to dismiss reviews on pull requests	Only taken into account when requires_pull_request is enabled
bypass_pull_request_allowances	list[Actor]	List of actors able to bypass pull requests	Only taken into account when requires_pull_request is enabled
require_last_push_approval	boolean	Whether the most recent push must be approved by someone other than the person who pushed it	Only taken into account when requires_pull_request is enabled
requires_status_checks	boolean	If enabled, status checks must pass before branches can be merged into a matching branch
requires_strict_status_checks	boolean	If enabled, pull requests targeting a matching branch must have been tested with the latest code.	This setting will not take effect unless at least one status check is enabled
required_status_checks	list[StatusCheck]	List of status checks that must succeed before branches can be merged	Only taken into account when requires_status_checks is enabled
requires_conversation_resolution	boolean	If enabled, all conversations on code must be resolved before a pull request can be merged into a matching branch
requires_commit_signatures	boolean	If enabled, commits pushed to matching branches must have verified signatures
requires_linear_history	boolean	If enabled, prevent merge commits from being pushed to matching branches
requires_deployments	boolean	If enabled, environments must be successfully deployed to before branches can be merged into a matching branch
required_deployment_environments	list[string]	List of environments that must be successfully deployed to before branches can be merged	Only taken into account when requires_deployments is enabled
lock_branch	boolean	If enabled, matching branches are read-only, users cannot push to the branch
lock_allows_fetch_and_merge	boolean	Whether users can pull changes from upstream when the branch is locked. Set to true to allow fork syncing. Set to false to prevent fork syncing
is_admin_enforced	boolean	If enabled, the above settings will apply to administrators and custom roles with the "bypass branch protections" permission as well
restricts_pushes	boolean	If enabled, only allowed actors (see push_restrictions) will be able to push to matching branches. Required status checks will still prevent these actors from merging if the checks fail
blocks_creations	boolean	If enabled, only allowed actors (see push_restrictions) will be able to create new branches matching this rule	Only taken into account when restricts_pushes is enabled
push_restrictions	list[Actor]	List of actors that are allowed to push to the matching branches	Only taken into account when restricts_pushes is enabled
allows_force_pushes	boolean	If enabled, actors with push permission can force push to matching branches	This property takes precedence over bypass_force_push_allowances if enabled, allowing all users with write access to force push
bypass_force_push_allowances	list[Actor]	List of actors able to force push to matching branches	This property is only taken into account when allows_force_pushes is disabled
allows_deletions	boolean	If enabled, allows actors with push permission to delete matching branches

Note

Property allows_force_pushes takes precedence of bypass_force_push_allowances. If it is enabled, any actor with write permissions can force push to matching branches. If you want to specify a list of actors that are allowed to force push, set allows_force_pushes to false and specify the allowed list of actors in bypass_force_push_allowances.

Jsonnet Function

orgs.newBranchProtectionRule('<pattern>') {
  <key>: <value>
}

Validation rules

• enabling a setting that is only taken into account when another setting is enabled, triggers a warning, e.g. dismisses_stale_reviews is only valid when requires_pull_request is enabled
• specifying a non-empty list for a setting that is only taken into account when another setting is enabled, triggers a warning as well, e.g. bypass_pull_request_allowances is only valid when requires_pull_request is enabled
• specifying an integer value for required_approving_review_count while requires_pull_request is disabled, triggers a warning, set it to null instead
• specifying a non-empty list of bypass_force_push_allowances actors while allows_force_pushes is enabled, triggers a warning
• specifying a non-empty list of review_dismissal_allowances actors while restricts_review_dismissals is disabled, triggers a warning
• specifying a non-empty list of push_restrictions actors while restricts_pushes is disabled, triggers a warning

Example usage

jsonnet

orgs.newOrg('adoptium') {
  ...
  _repositories+:: [
    ...
    orgs.newRepo('adoptium.net') {
      description: "Adoptium Website",
      homepage: "https://adoptium.net",
      branch_protection_rules: [
        orgs.newBranchProtectionRule('main') {
          required_approving_review_count: 1,
          required_status_checks+: [
            "Lint Code Base",
            "Run CI",
            "netlify:netlify/eclipsefdn-adoptium/deploy-preview"
          ],
        },
      ],
    },
  ],
}