|
1 | 1 | --- |
2 | 2 | title: About protected branches |
3 | | -intro: 'Protected branches ensure that collaborators on your repository cannot make irrevocable changes to branches. Enabling protected branches also allows you to enable other optional checks and requirements, like required status checks and required reviews.' |
| 3 | +intro: 'You can protect important branches by setting branch protection rules, which define whether collaborators can delete or force push to the branch and set requirements for any pushes to the branch, such as passing status checks or a linear commit history.' |
4 | 4 | product: '{% data reusables.gated-features.protected-branches %}' |
5 | 5 | redirect_from: |
6 | 6 | - /articles/about-protected-branches |
7 | 7 | - /enterprise/admin/developer-workflow/about-protected-branches-and-required-status-checks |
| 8 | + - /articles/about-branch-restrictions |
| 9 | + - /github/administering-a-repository/about-branch-restrictions |
| 10 | + - /articles/about-required-status-checks |
| 11 | + - /github/administering-a-repository/about-required-status-checks |
| 12 | + - /articles/types-of-required-status-checks |
| 13 | + - /github/administering-a-repository/types-of-required-status-checks |
| 14 | + - /articles/about-required-commit-signing |
| 15 | + - /github/administering-a-repository/about-required-commit-signing |
| 16 | + - /articles/about-required-reviews-for-pull-requests |
| 17 | + - /github/administering-a-repository/about-required-reviews-for-pull-requests |
8 | 18 | versions: |
9 | 19 | free-pro-team: '*' |
10 | 20 | enterprise-server: '*' |
11 | 21 | github-ae: '*' |
12 | 22 | --- |
13 | 23 |
|
14 | | -### About protected branches |
| 24 | +### About branch protection rules |
15 | 25 |
|
16 | | -{% data reusables.pull_requests.about-protected-branches %} You can choose to enforce restrictions on how a pull request is merged into your repository. |
| 26 | +You can enforce certain workflows or requirements before a collaborator can push changes to a branch in your repository, including merging a pull request into the branch, by creating a branch protection rule. |
17 | 27 |
|
18 | | -Repository owners and people with admin permissions for a repository can enforce certain workflows or requirements, before a collaborator can merge a branch in your repository by creating protected branch rules. |
| 28 | +By default, each branch protection rule disables force pushes to the matching branches and prevents the matching branches from being deleted. You can optionally disable these restrictions and enable additional branch protection settings. |
19 | 29 |
|
20 | | -{% data reusables.repositories.branch-rules-example %} For more information, see "[Configuring protected branches](/articles/configuring-protected-branches/)." |
| 30 | +By default, the restrictions of a branch protection rule don't apply to people with admin permissions to the repository. You can optionally choose to include administrators, too. |
| 31 | + |
| 32 | +{% data reusables.repositories.branch-rules-example %} For more information about branch name patterns, see "[Managing a branch protection rule](/github/administering-a-repository/managing-a-branch-protection-rule)." |
21 | 33 |
|
22 | 34 | {% data reusables.pull_requests.you-can-auto-merge %} |
23 | 35 |
|
24 | | -### Prioritization of protected branch rules |
| 36 | +### About branch protection settings |
| 37 | + |
| 38 | +For each branch protection rule, you can choose to enable or disable the following settings. |
| 39 | +- [Require pull request reviews before merging](#require-pull-request-reviews-before-merging) |
| 40 | +- [Require status checks before merging](#require-status-checks-before-merging) |
| 41 | +- [Require signed commits](#require-signed-commits) |
| 42 | +- [Require linear history](#require-linear-history) |
| 43 | +- [Include administrators](#include-administrators) |
| 44 | +- [Restrict who can push to matching branches](#restrict-who-can-push-to-matching-branches) |
| 45 | +- [Allow force pushes](#allow-force-pushes) |
| 46 | +- [Allow deletions](#allow-deletions) |
| 47 | + |
| 48 | +#### Require pull request reviews before merging |
| 49 | + |
| 50 | +{% data reusables.pull_requests.required-reviews-for-prs-summary %} |
| 51 | + |
| 52 | +If you enable required reviews, collaborators can only push changes to a protected branch via a pull request that is approved by the required number of reviewers with write permissions. |
| 53 | + |
| 54 | +If a person with admin permissions chooses the **Request changes** option in a review, then that person must approve the pull request before the pull request can be merged. If a reviewer who requests changes on a pull request isn't available, anyone with write permissions for the repository can dismiss the blocking review. |
| 55 | + |
| 56 | +{% data reusables.repositories.review-policy-overlapping-commits %} |
| 57 | + |
| 58 | +If a collaborator attempts to merge a pull request with pending or rejected reviews into the protected branch, the collaborator will receive an error message. |
| 59 | + |
| 60 | +```shell |
| 61 | +remote: error: GH006: Protected branch update failed for refs/heads/main. |
| 62 | +remote: error: Changes have been requested. |
| 63 | +``` |
| 64 | + |
| 65 | +Optionally, you can choose to dismiss stale pull request approvals when commits are pushed. If anyone pushes a commit that modifies code to an approved pull request, the approval will be dismissed, and the pull request cannot be merged. This doesn't apply if the collaborator pushes commits that don't modify code, like merging the base branch into the pull request's branch. For information about the base branch, see "[About pull requests](/articles/about-pull-requests)." |
| 66 | + |
| 67 | +Optionally, you can restrict the ability to dismiss pull request reviews to specific people or teams. For more information, see "[Dismissing a pull request review](/articles/dismissing-a-pull-request-review)." |
| 68 | + |
| 69 | +Optionally, you can choose to require reviews from code owners. If you do, any pull request that affects code with a code owner must be approved by that code owner before the pull request can be merged into the protected branch. |
| 70 | + |
| 71 | +#### Require status checks before merging |
| 72 | + |
| 73 | +Required status checks ensure that all required CI tests are passing before collaborators can make changes to a protected branch. Required status checks can be checks or statuses. For more information, see "[About status checks](/github/collaborating-with-issues-and-pull-requests/about-status-checks)." |
| 74 | + |
| 75 | +Before you can enable required status checks, you must configure the repository to use the status API. For more information, see "[Repositories](/rest/reference/repos#statuses)" in the REST documentation. |
| 76 | + |
| 77 | +After enabling required status checks, all required status checks must pass before collaborators can merge changes into the protected branch. After all required status checks pass, any commits must either be pushed to another branch and then merged or pushed directly to the protected branch. |
| 78 | + |
| 79 | +{% note %} |
| 80 | + |
| 81 | +**Note:** Any person or integration with write permissions to a repository can set the state of any status check in the repository. {% data variables.product.company_short %} does not verify that the author of a check is authorized to create a check with a certain name or modify an existing status. Before merging a pull request, you should verify that the author of each status, listed in the merge box, is expected. |
| 82 | + |
| 83 | +{% endnote %} |
| 84 | + |
| 85 | +You can set up required status checks to either be "loose" or "strict." The type of required status check you choose determines whether your branch is required to be up-to-date with the base branch before merging. |
| 86 | + |
| 87 | +| Type of required status check | Setting | Merge requirements | Considerations | |
| 88 | +| --- | --- | --- | --- | |
| 89 | +| **Strict** | The **Require branches to be up-to-date before merging** checkbox is checked. | The branch **must** be up to date with the base branch before merging. | This is the default behavior for required status checks. More builds may be required, as you'll need to bring the head branch up to date after other collaborators merge pull requests to the protected base branch.| |
| 90 | +| **Loose** | The **Require branches to be up-to-date before merging** checkbox is **not** checked. | The branch **does not** have to be up to date with the base branch before merging. | You'll have fewer required builds, as you won't need to bring the head branch up to date after other collaborators merge pull requests. Status checks may fail after you merge your branch if there are incompatible changes with the base branch. | |
| 91 | +| **Disabled** | The **Require status checks to pass before merging** checkbox is **not** checked. | The branch has no merge restrictions. | If required status checks aren't enabled, collaborators can merge the branch at any time, regardless of whether it is up to date with the base branch. This increases the possibility of incompatible changes. |
| 92 | + |
| 93 | +For troubleshooting information, see "[Troubleshooting required status checks](/github/administering-a-repository/troubleshooting-required-status-checks)." |
| 94 | + |
| 95 | +#### Require signed commits |
| 96 | + |
| 97 | +When you enable required commit signing on a branch, contributors {% if currentVersion == "free-pro-team@latest" %}and bots{% endif %} can only push commits that have been signed and verified to the branch. For more information, see "[About commit signature verification](/articles/about-commit-signature-verification)." |
| 98 | + |
| 99 | +{% note %} |
| 100 | + |
| 101 | +**Note:** If a collaborator pushes an unsigned commit to a branch that requires commit signatures, the collaborator will need to rebase the commit to include a verified signature, then force push the rewritten commit to the branch. |
| 102 | + |
| 103 | +{% endnote %} |
| 104 | + |
| 105 | +You can always push local commits to the branch if the commits are signed and verified. {% if currentVersion == "free-pro-team@latest" %}You can also merge signed and verified commits into the branch using a pull request on {% data variables.product.product_name %}. However, you cannot squash and merge a pull request into the branch on {% data variables.product.product_name %} unless you are the author of the pull request.{% else %} However, you cannot merge pull requests into the branch on {% data variables.product.product_name %}.{% endif %} You can {% if currentVersion == "free-pro-team@latest" %}squash and {% endif %}merge pull requests locally. For more information, see "[Checking out pull requests locally](/github/collaborating-with-issues-and-pull-requests/checking-out-pull-requests-locally)." |
| 106 | + |
| 107 | +{% if currentVersion == "free-pro-team@latest" %} For more information about merge methods, see "[About merge methods on {% data variables.product.prodname_dotcom %}](/github/administering-a-repository/about-merge-methods-on-github)."{% endif %} |
| 108 | + |
| 109 | +#### Require linear history |
| 110 | + |
| 111 | +Enforcing a linear commit history prevents collaborators from pushing merge commits to the branch. This means that any pull requests merged into the protected branch must use a squash merge or a rebase merge. A strictly linear commit history can help teams reverse changes more easily. For more information about merge methods, see "[About pull request merges](/github/collaborating-with-issues-and-pull-requests/about-pull-request-merges)." |
| 112 | + |
| 113 | +Before you can require a linear commit history, your repository must allow squash merging or rebase merging. For more information, see "[Configuring pull request merges](/github/administering-a-repository/configuring-pull-request-merges)." |
| 114 | + |
| 115 | +#### Include administrators |
| 116 | + |
| 117 | +By default, protected branch rules do not apply to people with admin permissions to a repository. You can enable this setting to include administrators in your protected branch rules. |
| 118 | + |
| 119 | +#### Restrict who can push to matching branches |
| 120 | + |
| 121 | +{% if currentVersion == "free-pro-team@latest" %} |
| 122 | +You can enable branch restrictions if your repository is owned by an organization using {% data variables.product.prodname_team %} or {% data variables.product.prodname_ghe_cloud %}. |
| 123 | +{% endif %} |
| 124 | + |
| 125 | +When you enable branch restrictions, only users, teams, or apps that have been given permission can push to the protected branch. You can view and edit the users, teams, or apps with push access to a protected branch in the protected branch's settings. |
| 126 | + |
| 127 | +You can only give push access to a protected branch to users, teams, or installed {% data variables.product.prodname_github_apps %} with write access to a repository. People and apps with admin permissions to a repository are always able to push to a protected branch. |
| 128 | + |
| 129 | +#### Allow force pushes |
25 | 130 |
|
26 | | -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. |
| 131 | +By default, {% data variables.product.product_name %} blocks force pushes on all protected branches. When you enable force pushes to a protected branch, anyone with at least write permissions to the repository can force push to the branch, including those with admin permissions. |
27 | 132 |
|
28 | | -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. |
| 133 | +Enabling force pushes will not override any other branch protection rules. For example, if a branch requires a linear commit history, you cannot force push merge commits to that branch. |
29 | 134 |
|
30 | | -### Branch protection settings |
| 135 | +{% if enterpriseServerVersions contains currentVersion or currentVersion == "github-ae@latest" %}You cannot enable force pushes for a protected branch if a site administrator has blocked force pushes to all branches in your repository. For more information, see "[Blocking force pushes to repositories owned by a user account or organization](/enterprise/{{ currentVersion }}/admin/developer-workflow/blocking-force-pushes-to-repositories-owned-by-a-user-account-or-organization)." |
31 | 136 |
|
32 | | -When you create a branch protection rule in a repository, collaborators cannot force push to the protected branch or delete the branch{% if currentVersion == "free-pro-team@latest" %} by default{% endif %}. You can enable other branch protection settings. For information, see "[Defining the mergeability of pull requests](/github/administering-a-repository/defining-the-mergeability-of-pull-requests)." |
| 137 | +If a site administrator has blocked force pushes to the default branch only, you can still enable force pushes for any other protected branch.{% endif %} |
33 | 138 |
|
34 | | -### Further reading |
| 139 | +#### Allow deletions |
35 | 140 |
|
36 | | -- "[About required status checks](/articles/about-required-status-checks)" |
37 | | -- "[About required reviews for pull requests](/articles/about-required-reviews-for-pull-requests)" |
38 | | -- "[About required commit signing](/articles/about-required-commit-signing)" |
| 141 | +By default, you cannot delete a protected branch. When you enable deletion of a protected branch, anyone with at least write permissions to the repository can delete the branch. |
0 commit comments