Skip to content

5. branch-protection.md

Latest commit

 

History

History
338 lines (293 loc) · 13.8 KB

5. branch-protection.md

File metadata and controls

338 lines (293 loc) · 13.8 KB

Configuring branch protection policies

Protected branches are available in public repositories with GitHub Free and GitHub Free for organizations, and in public and private repositories with GitHub Pro, GitHub Team, GitHub Enterprise Cloud, and GitHub Enterprise Server. For more information, see GitHub's products in the GitHub Help documentation.

Protecting a branch requires admin or owner permissions to the repository.

Note: Passing new arrays of users and teams replaces their previous values.

Note: The list of users, apps, and teams in total is limited to 100 items.

Note

This section can be applied to repos/<file>.yml or suborgs/<file>.yml. It will most commonly appear in the individual repos though.

Example branch protection definition

# These settings are synced to GitHub by https://github.com/github/safe-settings
branches:
  - name: default
    protection:
      required_pull_request_reviews:
        required_approving_review_count: 2
        dismiss_stale_reviews: true
        require_code_owner_reviews: true
        require_last_push_approval: true
        required_signatures: true
        require_linear_history: false
        bypass_pull_request_allowances:
          apps:
            - Jarvis
            - Edith
          users:
            - TonyStank
          teams:
            - Avengers
        dismissal_restrictions:
          users:
            - Hulk
          teams:
            - Revengers
      required_status_checks:
        strict: true
        checks:
          - stark-industries/barndoor-protocol
          - stark-industries/sokovia-accords
      enforce_admins: true
      restrictions:
        users:
          - starlord
        teams:
          - guardians

Branch Protection API Spec

Tip

GitHub's API documentation defines these inputs and types:

  1. Update branch protection

required_status_checks object or null ${\text{\color{orange}Required}}$

Require status checks to pass before merging. Set to null to disable.

Properties of required_status_checks

 strict boolean ${\text{\color{orange}Required}}$

  Require branches to be up to date before merging.

 contexts array of strings ${\text{\color{orange}Required}}$

  Deprecated: The list of status checks to require in order to merge into this branch. If any of these checks have recently been set by a particular GitHub App, they will be required to come from that app in future for the branch to merge. Use checks instead of contexts for more fine-grained control.

 checks array of strings ${\text{\color{orange}Required}}$

  The list of status checks to require in order to merge into this branch.

 Example: 
branches:
  - name: default
    protection:
      required_status_checks:
        strict: true
        checks:
          - stark-industries/barndoor-protocol
          - stark-industries/sokovia-accords
...

 enforce_admins boolean ${\text{\color{orange}Required}}$

Enforce all configured restrictions for administrators. Set to true to enforce required status checks for repository administrators. Set to null to disable.

 
branches:
  - name: default
    protection:
      required_status_checks:
        strict: true
        checks:
          - stark-industries/barndoor-protocol
          - stark-industries/sokovia-accords
      enforce_admins: true

required_pull_request_reviews object or null ${\text{\color{orange}Required}}$

Require at least one approving review on a pull request, before merging. Set to null to disable.

Properties of required_pull_request_reviews

 dismissal_restrictions object 

  Specify which users, teams, and apps can dismiss pull request reviews. Pass an empty dismissal_restrictions object to disable. User and team dismissal_restrictions are only available for organization-owned repositories. Omit this parameter for personal repositories.

Properties of dismissal_restrictions

 users array of strings

  The list of user logins with dismissal access.

 teams array of strings

  The list of team slugs with dismissal access.

 apps array of strings

  The list of app slugs with dismissal access.

 dismiss_stale_reviews boolean 

  Set to true if you want to automatically dismiss approving reviews when someone pushes a new commit.

 require_code_owner_reviews boolean 

  Blocks merging pull requests until code owners review them.

 required_approving_review_count integer 

  Specify the number of reviewers required to approve pull requests. Use a number between 1 and 6 or 0 to not require reviewers.

 require_last_push_approval boolean 

  Whether the most recent push must be approved by someone other than the person who pushed it.

Default: false.

 bypass_pull_request_allowances object 

  Allow specific users, teams, or apps to bypass pull request requirements.

Properties of bypass_pull_request_allowances

 users array of strings

  The list of user logins allowed to bypass pull request requirements.

 teams array of strings

  The list of team slugs allowed to bypass pull request requirements.

 apps array of strings

  The list of app slugs allowed to bypass pull request requirements.

 
branches:
  - name: default
    protection:
      required_pull_request_reviews:
        required_approving_review_count: 2
        dismiss_stale_reviews: true
        require_code_owner_reviews: true
        require_last_push_approval: true
        required_signatures: true
        bypass_pull_request_allowances:
          apps:
            - Jarvis
            - Edith
          users:
            - TonyStank
          teams:
            - Avengers
        dismissal_restrictions:
          users:
            - Hulk
          teams:
            - Revengers
...

restrictions object or null ${\text{\color{orange}Required}}$

Restrict who can push to the protected branch. User, app, and team restrictions are only available for organization-owned repositories. Set to null to disable.

Properties of restrictions

 users array of strings

  The list of user logins with push access.

 teams array of strings

  The list of team slugs with push access.

 apps array of strings

  The list of app slugs with push access.

 Example: 
branches:
  - name: default
    protection:
      ...
      restrictions:
        users:
          - superman
        teams:
          - justice-league
...

 required_linear_history boolean 

Enforces a linear commit Git history, which prevents anyone from pushing merge commits to a branch. Set to true to enforce a linear commit history. Set to false to disable a linear commit Git history. Your repository must allow squash merging or rebase merging before you can enable a linear commit history. For more information, see "Requiring a linear commit history" in the GitHub Help documentation.

Default: false

 
branches:
  - name: default
    protection:
      require_linear_history: false
...

 allow_force_pushes boolean or null 

Permits force pushes to the protected branch by anyone with write access to the repository. Set to true to allow force pushes. Set to false or null to block force pushes. Default: false. For more information, see "Enabling force pushes to a protected branch" in the GitHub Help documentation.

 
branches:
  - name: default
    protection:
      allow_force_pushes: false
...

 allow_deletions boolean 

Allows deletion of the protected branch by anyone with write access to the repository. Set to false to prevent deletion of the protected branch. For more information, see "Enabling force pushes to a protected branch" in the GitHub Help documentation.

Default: false

 
branches:
  - name: default
    protection:
      allow_deletions: false
...

 block_creations boolean 

If set to true, the restrictions branch protection settings which limits who can push will also block pushes which create new branches, unless the push is initiated by a user, team, or app which has the ability to push. Set to true to restrict new branch creation.

Default: false

 
branches:
  - name: default
    protection:
      block_creations: false
...

 required_conversation_resolution boolean 

Requires all conversations on code to be resolved before a pull request can be merged into a branch that matches this rule. Set to false to disable.

Default: false

 
branches:
  - name: default
    protection:
      required_conversation_resolution: false
...

 lock_branch boolean 

Whether to set the branch as read-only. If this is true, users will not be able to push to the branch.

Default: false

 
branches:
  - name: default
    protection:
      lock_branch: false
...

 allow_fork_syncing 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.

Default: false

 
branches:
  - name: default
    protection:
      allow_fork_syncing: false
...

 required_signatures boolean 

Whether users are required to configure SSH or GPG signatures for all commits pushed to this branch.

Default: false

 
branches:
  - name: default
    protection:
      required_signatures: true
...