Skip to main content
The branches section configures branch protection rules for repositories. Branch protection enforces certain workflows, such as requiring pull request reviews or status checks before merging.

​
Basic Configuration

​
name
string
required
The name of the branch to protect. Use default to protect the repository’s default branch (dynamically resolved).
branches:
  - name: main
    protection:
      # protection settings
  - name: default
    protection:
      # applies to default branch

​
Protection Settings

​
protection
object
Branch protection configuration. Set to null or {} to remove branch protection.
branches:
  - name: main
    protection: null  # removes protection

​
Pull Request Reviews

​
protection.required_pull_request_reviews
object
Require at least one approving review on a pull request before merging. Set to null to disable.
​
required_approving_review_count
integer
The number of approvals required (1-6).
​
dismiss_stale_reviews
boolean
Dismiss approved reviews automatically when a new commit is pushed.
​
require_code_owner_reviews
boolean
Blocks merge until code owners have reviewed.
​
require_last_push_approval
boolean
Whether the most recent reviewable push must be approved by someone other than the person who pushed it.
​
bypass_pull_request_allowances
object
Allow specific users, teams, or apps to bypass pull request requirements. Set to null to disable.
​
apps
array
Array of app slugs allowed to bypass.
​
users
array
Array of usernames allowed to bypass.
​
teams
array
Array of team slugs allowed to bypass.
​
dismissal_restrictions
object
Specify which users and teams can dismiss pull request reviews. User and team dismissal_restrictions are only available for organization-owned repositories.
​
users
array
Array of usernames.
​
teams
array
Array of team slugs.
branches:
  - name: main
    protection:
      required_pull_request_reviews:
        required_approving_review_count: 1
        dismiss_stale_reviews: true
        require_code_owner_reviews: true
        require_last_push_approval: true
        bypass_pull_request_allowances:
          apps: []
          users: []
          teams: []
        dismissal_restrictions:
          users: []
          teams: []

​
Status Checks

​
protection.required_status_checks
object
Require status checks to pass before merging. Set to null to disable.
​
strict
boolean
required
Require branches to be up to date before merging.
​
contexts
array
required
The list of status checks to require in order to merge into this branch. Use {{EXTERNALLY_DEFINED}} as a special value to allow status checks to be managed outside of Safe Settings (prevents Safe Settings from overwriting manually added checks).
branches:
  - name: main
    protection:
      required_status_checks:
        strict: true
        contexts:
          - CI
          - CodeQL

​
Using {{EXTERNALLY_DEFINED}}

When you include {{EXTERNALLY_DEFINED}} in the contexts array, Safe Settings will not manage the status checks list. This allows you to add status checks manually through the GitHub UI or other tools.
branches:
  - name: main
    protection:
      required_status_checks:
        strict: true
        contexts:
          - '{{EXTERNALLY_DEFINED}}'

​
Administrator Enforcement

​
protection.enforce_admins
boolean
Enforce all configured restrictions for administrators. Set to true to enforce required status checks for repository administrators. Set to null to disable.
branches:
  - name: main
    protection:
      enforce_admins: true

​
Push Restrictions

​
protection.restrictions
object
Restrict who can push to this branch. Team and user restrictions are only available for organization-owned repositories. Set to null to disable.
​
apps
array
Array of app slugs.
​
users
array
Array of usernames.
​
teams
array
Array of team slugs.
branches:
  - name: main
    protection:
      restrictions:
        apps: []
        users: []
        teams: []

​
Additional Protection Rules

​
protection.required_conversation_resolution
boolean
Require all conversations on code to be resolved before a pull request can be merged.
branches:
  - name: main
    protection:
      required_conversation_resolution: true
​
protection.required_linear_history
boolean
Require linear history (prevent merge commits).
branches:
  - name: main
    protection:
      required_linear_history: true
​
protection.required_signatures
boolean
Require signed commits.
branches:
  - name: main
    protection:
      required_signatures: true
​
protection.allow_deletions
boolean
Allow users with push access to delete matching branches.
branches:
  - name: main
    protection:
      allow_deletions: false

​
Complete Example

branches:
  - name: default
    protection:
      required_pull_request_reviews:
        required_approving_review_count: 1
        dismiss_stale_reviews: true
        require_code_owner_reviews: true
        require_last_push_approval: true
        bypass_pull_request_allowances:
          apps: []
          users: []
          teams: []
        dismissal_restrictions:
          users: []
          teams: []
      required_status_checks:
        strict: true
        contexts:
          - CI
          - CodeQL
      enforce_admins: true
      restrictions:
        apps: []
        users: []
        teams: []
      required_conversation_resolution: true
      required_linear_history: false
      required_signatures: false
      allow_deletions: false

​
Removing Branch Protection

To remove branch protection from a branch: 
branches:
  - name: develop
    protection: {}  # or null

​
API Reference

For more details, see GitHub’s REST API documentation:

Build docs developers (and LLMs) love

Get started for freeTalk to us