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](https://ruby-doc.org/core-2.5.1/File.html#method-c-fnmatch), see [doc@GitHub](https://docs.github.com/en/repositories/configuring-branches-and-merges-in-your-repository/managing-protected-branches/managing-a-branch-protection-rule#about-branch-protection-rules) 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](actor.md)\]              | 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](actor.md)\]              | 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](status-check.md)\] | 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](actor.md)\]              | 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](actor.md)\]              | 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

``` jsonnet
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"
    ``` 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"
              ],
            },
          ],
        },
      ],
    }
    ```
