[2023-06-07]: Security Changes for Pull Request Mergeability - [GA] (#36620)

Co-authored-by: Isaac Brown <101839405+isaacmbrown@users.noreply.github.com>
Co-authored-by: Patrick Knight <patrick-knight@github.com>

content/repositories/configuring-branches-and-merges-in-your-repository/managing-protected-branches/about-protected-branches.md

@@ -42,11 +42,11 @@ By default, the restrictions of a branch protection rule don't apply to people w
 {% data reusables.pull_requests.you-can-auto-merge %}
 
 {% ifversion repo-rules %}
-{% tip %}
+{% note %}
 
-**Tip:** Only a single branch protection rule can apply at a time, which means it can be difficult to know which rule will apply when multiple versions of a rule target the same branch. {% ifversion repo-rules-enterprise %}Additionally, you may want to create a single set of rules that applies to multiple repositories in an organization. {% endif %}For information about an alternative to branch protection rules, see "[AUTOTITLE](/repositories/configuring-branches-and-merges-in-your-repository/managing-rulesets/about-rulesets)."
+**Note:** Only a single branch protection rule can apply at a time, which means it can be difficult to know which rule will apply when multiple versions of a rule target the same branch. {% ifversion repo-rules-enterprise %}Additionally, you may want to create a single set of rules that applies to multiple repositories in an organization. {% endif %}For information about an alternative to branch protection rules, see "[AUTOTITLE](/repositories/configuring-branches-and-merges-in-your-repository/managing-rulesets/about-rulesets)."
 
-{% endtip %}
+{% endnote %}
 {% endif %}
 
 ## About branch protection settings
@@ -102,6 +102,10 @@ Optionally, you can require that the most recent reviewable push must be approve
 For complex pull requests that require many reviews, requiring an approval from someone other than the last person to push can be a compromise that avoids the need to dismiss all stale reviews: with this option, "stale" reviews are not dismissed, and the pull request remains approved as long as someone other than the person who made the most recent changes approves it. Users who have already reviewed a pull request can reapprove after the most recent push to meet this requirement. If you are concerned about pull requests being "hijacked" (where unapproved content is added to approved pull requests), it is safer to dismiss stale reviews.
 {% endif %}
 
+{% ifversion pull-request-mergeability-security-changes %}
+{% data reusables.pull_requests.security-changes-mergeability %}
+{% endif %}
+
 ### Require status checks before merging
 
 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 "[AUTOTITLE](/pull-requests/collaborating-with-pull-requests/collaborating-on-repositories-with-code-quality-features/about-status-checks)."

content/repositories/configuring-branches-and-merges-in-your-repository/managing-protected-branches/managing-a-branch-protection-rule.md

@@ -44,11 +44,11 @@ To create an exception to an existing branch rule, you can create a new branch p
 For more information about each of the available branch protection settings, see "[AUTOTITLE](/repositories/configuring-branches-and-merges-in-your-repository/managing-protected-branches/about-protected-branches)."
 
 {% ifversion repo-rules %}
-{% tip %}
+{% note %}
 
-**Tip:** Only a single branch protection rule can apply at a time, which means it can be difficult to know how which rule will apply when multiple versions of a rule target the same branch. {% ifversion repo-rules-enterprise %}Additionally, you may want to create a single set of rules that applies to multiple repositories in an organization. {% endif %}For information about an alternative to branch protection rules, see "[AUTOTITLE](/repositories/configuring-branches-and-merges-in-your-repository/managing-rulesets/about-rulesets)."
+**Note:** Only a single branch protection rule can apply at a time, which means it can be difficult to know how which rule will apply when multiple versions of a rule target the same branch. {% ifversion repo-rules-enterprise %}Additionally, you may want to create a single set of rules that applies to multiple repositories in an organization. {% endif %}For information about an alternative to branch protection rules, see "[AUTOTITLE](/repositories/configuring-branches-and-merges-in-your-repository/managing-rulesets/about-rulesets)."
 
-{% endtip %}
+{% endnote %}
 {% endif %}
 
 ## Creating a branch protection rule
@@ -60,6 +60,9 @@ When you create a branch rule, the branch you specify doesn't have to exist yet
 {% data reusables.repositories.repository-branches %}
 {% data reusables.repositories.add-branch-protection-rules %}
 1. Optionally, enable required pull requests.
+{% ifversion pull-request-mergeability-security-changes %}
+{% indented_data_reference reusables.pull_requests.security-changes-mergeability spaces=3 %}
+{% endif %}
    - Under "Protect matching branches", select **Require a pull request before merging**.
    - Optionally, to require approvals before a pull request can be merged, select **Require approvals**.
 

content/repositories/configuring-branches-and-merges-in-your-repository/managing-rulesets/available-rules-for-rulesets.md

@@ -12,7 +12,7 @@ shortTitle: Available rules
 
 {% data reusables.repositories.rulesets-public-beta %}
 
-You can create rulesets to control how users can interact with selected branches and tags in a repository. When you create a ruleset, you can choose to enable or disable the rules described in the following sections. 
+You can create rulesets to control how users can interact with selected branches and tags in a repository. When you create a ruleset, you can choose to enable or disable the rules described in the following sections.
 
 When you create a ruleset, you can allow certain users to bypass the rules in the ruleset. This can be users with certain permissions, specific teams, or {% data variables.product.prodname_github_apps %}. For more information, see "[AUTOTITLE](/repositories/configuring-branches-and-merges-in-your-repository/managing-rulesets/about-rulesets)."
 
@@ -76,6 +76,10 @@ You can require that all changes to the target branch be associated with a pull
 
 ### Additional settings
 
+{% ifversion pull-request-mergeability-security-changes %}
+{% data reusables.pull_requests.security-changes-mergeability %}
+{% endif %}
+
 {% data reusables.pull_requests.required-reviews-for-prs-summary %}
 
 If you enable required reviews, collaborators can only push changes to a branch via a pull request that is approved by the required number of reviewers with write permissions.

data/features/pull-request-mergeability-security-changes.yml

@@ -0,0 +1,5 @@
+# Issue 10179 - Security Changes for Pull Request Mergeability
+versions:
+  fpt: '*'
+  ghec: '*'
+  ghes: '>=3.10'

data/reusables/pull_requests/security-changes-mergeability.md

@@ -0,0 +1,7 @@
+{% note %}
+
+**Note:** If you select **Dismiss stale pull request approvals when new commits are pushed** and/or **Require 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 {% data variables.product.prodname_dotcom %} 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.
+
+{% endnote %}