About branch protection rules

You can create a branch protection rule in a repository for a specific branch, all branches, or any branch that matches a name pattern you specify withfnmatch syntax. For example, to protect any branches containing the wordrelease, you can create a branch rule for*release*.

You can create a rule for all current and future branches in your repository with the wildcard syntax*. Because GitHub uses theFile::FNM_PATHNAME flag for theFile.fnmatch syntax, the* wildcard does not match directory separators (/). For example,qa/* will match all branches beginning withqa/ and containing a single slash, but will not matchqa/foo/bar. You can include any number of slashes afterqa withqa/**/*, which would match, for example,qa/foo/bar/foobar/hello-world. You can also extend theqa string withqa**/**/* to make the rule more inclusive.

For more information about syntax options, see thefnmatch documentation.

If a repository has multiple protected branch rules that affect the same branches, the rules that include a specific branch name have the highest priority. If there is more than one protected branch rule that references the same specific branch name, then the branch rule created first will have higher priority.

Protected branch rules that mention a special character, such as*,?, or], are applied in the order they were created, so older rules with these characters have a higher priority.

To create an exception to an existing branch rule, you can create a new branch protection rule that is higher priority, such as a branch rule for a specific branch name.

For more information about each of the available branch protection settings, seeAbout protected branches.

Creating a branch protection rule

When you create a branch rule, the branch you specify doesn't have to exist yet in the repository.

1. On GitHub, navigate to the main page of the repository.

2. Under your repository name, click Settings. If you cannot see the "Settings" tab, select the dropdown menu, then clickSettings.

   

3. In the "Code and automation" section of the sidebar, click Branches.

4. Next to "Branch protection rules", clickAdd rule.

5. Under "Branch name pattern", type the branch name or pattern you want to protect.

6. Optionally, enable required pull requests.

   Note

   If you selectDismiss stale pull request approvals when new commits are pushed and/orRequire approval of the most recent reviewable push, manually creating the merge commit for a pull request and pushing it directly to a protected branch will fail, unless the contents of the merge exactly match the merge generated by GitHub for the pull request.

   In addition, with these settings, approving reviews will be dismissed as stale if the merge base introduces new changes after the review was submitted. The merge base is the commit that is the last common ancestor between the topic branch and the base branch. If the merge base changes, the pull request cannot be merged until someone approves the work again.

   • Under "Protect matching branches", selectRequire a pull request before merging.

   • Optionally, to require approvals before a pull request can be merged, selectRequire approvals.

     Select theRequired number of approvals before merging dropdown menu, then click the number of approving reviews you would like to require on the branch.

   • Optionally, to dismiss a pull request approval review when a code-modifying commit is pushed to the branch, selectDismiss stale pull request approvals when new commits are pushed.

   • Optionally, to require review from a code owner when the pull request affects code that has a designated owner, selectRequire review from Code Owners. Note that if code has multiple owners, an approval fromany of the code owners will be sufficient to meet this requirement. For more information, seeAbout code owners.

   • Optionally, to allow specific actors to push code to the branch without creating pull requests when they're required, selectAllow specified actors to bypass required pull requests. Then, search for and select the actors who should be allowed to skip creating a pull request.

   • Optionally, if the repository is part of an organization, selectRestrict who can dismiss pull request reviews. Then, in the search field, search for and select the actors who are allowed to dismiss pull request reviews. For more information, seeDismissing a pull request review.

   • Optionally, to require someone other than the last person to push to a branch to approve a pull request prior to merging, selectRequire approval of the most recent reviewable push. For more information, seeAbout protected branches.

7. Optionally, enable required status checks. For more information, seeAbout status checks.

   • SelectRequire status checks to pass before merging.
   • Optionally, to ensure that pull requests are tested with the latest code on the protected branch, selectRequire branches to be up to date before merging.
   • In the search field, search for status checks, selecting the checks you want to require.

8. Optionally, selectRequire conversation resolution before merging.

9. Optionally, selectRequire signed commits.

10. Optionally, selectRequire linear history.

11. Optionally, to merge pull requests using a merge queue, selectRequire merge queue. For more information about merge queues, seeManaging a merge queue.

12. Optionally, to choose which environments the changes must be successfully deployed to before merging, selectRequire deployments to succeed before merging, then select the environments.

13. Optionally, make the branch read-only.

    • SelectLock branch.
    • Optionally, to allow fork syncing, selectAllow fork syncing.

14. Optionally, selectDo not allow bypassing the above settings.

15. Optionally, in public repositories owned by a GitHub Free organization and in all repositories owned by an organization using GitHub Team or GitHub Enterprise Cloud, enable branch restrictions.

    • SelectRestrict who can push to matching branches.
    • Optionally, to also restrict the creation of matching branches, selectRestrict pushes that create matching branches.
    • In the search field, search for and select the people, teams, or apps who will have permission to push to the protected branch or create a matching branch.

16. Optionally, under "Rules applied to everyone including administrators", selectAllow force pushes.

    Then, choose who can force push to the branch.

    • SelectEveryone to allow everyone with at least write permissions to the repository to force push to the branch, including those with admin permissions.
    • SelectSpecify who can force push to allow only specific actors to force push to the branch. Then, search for and select those actors.

    For more information about force pushes, seeAbout protected branches.

17. Optionally, selectAllow deletions.

18. ClickCreate.

Editing a branch protection rule

1. On GitHub, navigate to the main page of the repository.

2. Under your repository name, click Settings. If you cannot see the "Settings" tab, select the dropdown menu, then clickSettings.

   

3. In the "Code and automation" section of the sidebar, click Branches.

4. To the right of the branch protection rule you want to edit, clickEdit.

5. Make your desired changes to the branch protection rule.

6. ClickSave changes.

Deleting a branch protection rule

1. On GitHub, navigate to the main page of the repository.

2. Under your repository name, click Settings. If you cannot see the "Settings" tab, select the dropdown menu, then clickSettings.

   

3. In the "Code and automation" section of the sidebar, click Branches.

4. To the right of the branch protection rule you want to delete, clickDelete.