Code scanning: Improve experience for code scanning PR merge protection functionality for Rulesets [GA] (#50259)

Co-authored-by: github-actions <github-actions@github.com>
Co-authored-by: Sarita Iyer <66540150+saritai@users.noreply.github.com>

content/code-security/code-scanning/creating-an-advanced-setup-for-code-scanning/customizing-your-advanced-setup-for-code-scanning.md

@@ -237,6 +237,16 @@ If your workflow does not contain a matrix called `language`, then {% data varia
 
 ## Defining the alert severities that cause a check failure for a pull request
 
+{% ifversion code-scanning-merge-protection-rulesets %}
+
+You can use rulesets to prevent pull requests from being merged when one of the following conditions is met:
+
+{% data reusables.code-scanning.merge-protection-rulesets-conditions %}
+
+For more information, see "[AUTOTITLE](/code-security/code-scanning/managing-your-code-scanning-configuration/set-code-scanning-merge-protection)." For more general information about rulesets, see "[AUTOTITLE](/repositories/configuring-branches-and-merges-in-your-repository/managing-rulesets/about-rulesets)."
+
+{% else %}
+
 {% data reusables.code-scanning.pull-request-checks %}
 
 {% ifversion code-scanning-without-workflow %}
@@ -251,6 +261,7 @@ You can edit which severity and security severity alert levels cause a check fai
 1. Under "{% data variables.product.prodname_code_scanning_caps %}", in the "Protection rules" section, use the drop-down menu to define which alerts should cause a check failure. Choose one level for alerts of type "Security" and one level for all other alerts.{% else %}
 1. Under "{% data variables.product.prodname_code_scanning_caps %}", to the right of "Check Failure", use the drop-down menu to select the level of severity you would like to cause a pull request check failure.{% endif %}
 
+{% endif %}
 {% endif %}
 
 ## Configuring a category for the analysis

content/code-security/code-scanning/enabling-code-scanning/configuring-default-setup-for-code-scanning-at-scale.md

@@ -174,3 +174,17 @@ You can select all of the displayed repositories, or a subset of them, and enabl
   If you're blocked from enabling {% data variables.product.prodname_code_scanning %} due to an enterprise policy, you will still be able to see the affected repository in the "Security Coverage" view and access the side panel from the **{% octicon "gear" aria-hidden="true" %} Security settings** button. However, you will see a message in the side panel indicating that you cannot enable {% data variables.product.prodname_code_scanning %} for the selected repositories. For more information about enterprise policies, see "[AUTOTITLE](/admin/policies/enforcing-policies-for-your-enterprise/enforcing-policies-for-code-security-and-analysis-for-your-enterprise)."
 
 {% endif %}
+
+{% ifversion code-scanning-merge-protection-rulesets %}
+{% ifversion ghes or ghec %}
+
+## Configuring merge protection for all repositories in an organization
+
+You can use rulesets to prevent pull requests from being merged when one of the following conditions is met:
+
+{% data reusables.code-scanning.merge-protection-rulesets-conditions %}
+
+For more information, see "[AUTOTITLE](/code-security/code-scanning/managing-your-code-scanning-configuration/set-code-scanning-merge-protection#creating-a-merge-protection-ruleset-for-all-repositories-in-an-organization)." For more general information about rulesets, see "[AUTOTITLE](/repositories/configuring-branches-and-merges-in-your-repository/managing-rulesets/about-rulesets)."
+
+{% endif %}
+{% endif %}

content/code-security/code-scanning/managing-code-scanning-alerts/about-code-scanning-alerts.md

@@ -99,10 +99,22 @@ When an alert has a security severity level, {% data variables.product.prodname_
 
 ### Pull request check failures for {% data variables.product.prodname_code_scanning %} alerts
 
+{% ifversion code-scanning-merge-protection-rulesets %}
+
+You can use rulesets to prevent pull requests from being merged when one of the following conditions is met:
+
+{% data reusables.code-scanning.merge-protection-rulesets-conditions %}
+
+For more information, see "[AUTOTITLE](/code-security/code-scanning/managing-your-code-scanning-configuration/set-code-scanning-merge-protection)." For more general information about rulesets, see "[AUTOTITLE](/repositories/configuring-branches-and-merges-in-your-repository/managing-rulesets/about-rulesets)."
+
+{% else %}
+
 {% data reusables.code-scanning.pull-request-checks %}
 
 You can edit which severity and security severity alert levels cause a check failure. For more information, see {% ifversion code-scanning-without-workflow %}"[AUTOTITLE](/code-security/code-scanning/managing-your-code-scanning-configuration/editing-your-configuration-of-default-setup#defining-the-alert-severities-that-cause-a-check-failure-for-a-pull-request){% else %}"[AUTOTITLE](/code-security/code-scanning/creating-an-advanced-setup-for-code-scanning/customizing-your-advanced-setup-for-code-scanning#defining-the-alert-severities-that-cause-a-check-failure-for-a-pull-request){% endif %}."
 
+{% endif %}
+
 ### Calculation of security severity levels
 
 When a security query is added to the {% data variables.product.prodname_codeql %} Default or Extended query suite, the {% data variables.product.prodname_codeql %} engineering team calculates the security severity as follows.

content/code-security/code-scanning/managing-your-code-scanning-configuration/editing-your-configuration-of-default-setup.md

@@ -56,6 +56,16 @@ If you need to change any other aspects of your {% data variables.product.prodna
 
 ## Defining the alert severities that cause a check failure for a pull request
 
+{% ifversion code-scanning-merge-protection-rulesets %}
+
+You can use rulesets to prevent pull requests from being merged when one of the following conditions is met:
+
+{% data reusables.code-scanning.merge-protection-rulesets-conditions %}
+
+For more information, see "[AUTOTITLE](/code-security/code-scanning/managing-your-code-scanning-configuration/set-code-scanning-merge-protection)." For more general information about rulesets, see "[AUTOTITLE](/repositories/configuring-branches-and-merges-in-your-repository/managing-rulesets/about-rulesets)."
+
+{% else %}
+
 {% data reusables.code-scanning.pull-request-checks %}
 
 {% data reusables.repositories.navigate-to-repo %}
@@ -64,6 +74,8 @@ If you need to change any other aspects of your {% data variables.product.prodna
 1. Under "{% data variables.product.prodname_code_scanning_caps %}", in the "Protection rules" section, use the drop-down menu to define which alerts should cause a check failure. Choose one level for alerts of type "Security" and one level for all other alerts.{% else %}
 1. Under "{% data variables.product.prodname_code_scanning_caps %}", to the right of "Check Failure", use the drop-down menu to select the level of severity you would like to cause a pull request check failure.{% endif %}
 
+{% endif %}
+
 {% ifversion codeql-threat-models %}
 
 ## Including local sources of tainted data in default setup

content/code-security/code-scanning/managing-your-code-scanning-configuration/index.md

@@ -14,6 +14,7 @@ topics:
 children:
   - /about-the-tool-status-page
   - /editing-your-configuration-of-default-setup
+  - /set-code-scanning-merge-protection
   - /codeql-query-suites
   - /configuring-larger-runners-for-default-setup
   - /viewing-code-scanning-logs

content/code-security/code-scanning/managing-your-code-scanning-configuration/set-code-scanning-merge-protection.md

@@ -0,0 +1,65 @@
+---
+title: Set code scanning merge protection
+shortTitle: Set merge protection
+intro: 'You can use rulesets to set {% data variables.product.prodname_code_scanning %} merge protection for pull requests.'
+product: '{% data reusables.gated-features.code-scanning %}'
+versions:
+  feature: code-scanning-merge-protection-rulesets
+type: how_to
+topics:
+  - Code scanning
+  - CodeQL
+---
+
+## About using rulesets for {% data variables.product.prodname_code_scanning %} merge protection
+
+{% note %}
+
+**Notes:**
+
+- This feature is currently in beta and subject to change.
+- Merge protection with rulesets is not related to status checks. For more information about status checks, see "[AUTOTITLE](/pull-requests/collaborating-with-pull-requests/collaborating-on-repositories-with-code-quality-features/about-status-checks)."
+
+{% endnote %}
+
+You can use rulesets to prevent pull requests from being merged when one of the following conditions is met:
+
+{% data reusables.code-scanning.merge-protection-rulesets-conditions %}
+
+For more information about {% data variables.product.prodname_code_scanning %} alerts, see "[AUTOTITLE](/code-security/code-scanning/managing-code-scanning-alerts/about-code-scanning-alerts)."
+
+You can set merge protection with rulesets at the repository {% ifversion ghec or ghes %}or organization levels{% else %}level{% endif %}, and for repositories configured with either default setup or advanced setup. You can also use the REST API to set merge protection with rulesets.
+
+For more information about rulesets, see "[AUTOTITLE](/repositories/configuring-branches-and-merges-in-your-repository/managing-rulesets/about-rulesets)."
+
+## Creating a merge protection ruleset for a repository
+
+{% data reusables.repositories.navigate-to-repo %}
+{% data reusables.repositories.sidebar-settings %}
+{% data reusables.repositories.repo-rulesets-settings %}
+1. Click **New ruleset**.
+1. To create a ruleset targeting branches, click **New branch ruleset**.
+{% data reusables.repositories.rulesets-general-step %}
+{% data reusables.repositories.rulesets-require-code-scanning-results %}
+
+For more information about managing rulesets in a repository, see "[AUTOTITLE](/repositories/configuring-branches-and-merges-in-your-repository/managing-rulesets/)."
+
+{% ifversion ghec or ghes %}
+
+## Creating a merge protection ruleset for all repositories in an organization
+
+{% data reusables.profile.access_org %}
+{% data reusables.profile.org_settings %}
+{% data reusables.organizations.access-ruleset-settings %}
+1. Click **New ruleset**.
+1. To create a ruleset targeting branches, click **New branch ruleset**.
+{% data reusables.repositories.rulesets-general-step %}
+{% data reusables.repositories.rulesets-require-code-scanning-results %}
+
+For more information about managing rulesets for repositories in an organization, see "[AUTOTITLE](/organizations/managing-organization-settings/managing-rulesets-for-repositories-in-your-organization)."
+
+{% endif %}
+
+## Creating a merge protection ruleset with the REST API
+
+You can use the REST API to create a ruleset with the `code_scanning` rule, which allows you to define specific tools and set alert thresholds. For more information, see "[AUTOTITLE](/rest/repos/rules?apiVersion=2022-11-28#create-a-repository-ruleset)."

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

@@ -157,6 +157,18 @@ You can think of required status checks as being either "loose" or "strict." The
 
 For troubleshooting information, see "[AUTOTITLE](/pull-requests/collaborating-with-pull-requests/collaborating-on-repositories-with-code-quality-features/troubleshooting-required-status-checks)."
 
+{% ifversion code-scanning-merge-protection-rulesets %}
+
+## Set {% data variables.product.prodname_code_scanning %} merge protection
+
+If your repositories are configured with {% data variables.product.prodname_code_scanning %}, you can use rulesets to prevent pull requests from being merged when one of the following conditions is met:
+
+{% data reusables.code-scanning.merge-protection-rulesets-conditions %}
+
+For more information, see "[AUTOTITLE](/code-security/code-scanning/managing-your-code-scanning-configuration/set-code-scanning-merge-protection)." For more general information about {% data variables.product.prodname_code_scanning %}, see "[AUTOTITLE](/code-security/code-scanning/introduction-to-code-scanning/about-code-scanning)."
+
+{% endif %}
+
 ## Block force pushes
 
 You can prevent users from force pushing to the targeted branches or tags. This rule is enabled by default.

data/features/code-scanning-merge-protection-rulesets.yml

@@ -0,0 +1,5 @@
+# Reference: #13169
+versions:
+  fpt: '*'
+  ghec: '*'
+  ghes: '>3.13'

data/reusables/code-scanning/merge-protection-rulesets-conditions.md

@@ -0,0 +1,5 @@
+- A required tool found a {% data variables.product.prodname_code_scanning %} alert of a severity that is defined in a ruleset.
+
+- A required {% data variables.product.prodname_code_scanning %} tool's analysis is still in progress.
+
+- A required {% data variables.product.prodname_code_scanning %} tool is not configured for the repository.

data/reusables/code-scanning/pull-request-checks.md

@@ -1 +1 @@
-When you enable {% data variables.product.prodname_code_scanning %} on pull requests the check fails only if one or more alerts of severity `error`, or security severity `critical` or `high` are detected. The check will succeed if alerts with lower severities or security severities are detected. For important codebases, you may want the {% data variables.product.prodname_code_scanning %} check to fail if any alerts are detected, so that the alert must be fixed or dismissed before the code change is merged. For more information about severity levels, see "[About alert severity and security severity levels](/code-security/code-scanning/managing-code-scanning-alerts/about-code-scanning-alerts#about-alert-severity-and-security-severity-levels)."
+When you enable {% data variables.product.prodname_code_scanning %} on pull requests, the check fails only if one or more alerts of severity `error`, or security severity `critical` or `high` are detected. The check will succeed if alerts with lower severities or security severities are detected. For important codebases, you may want the {% data variables.product.prodname_code_scanning %} check to fail if any alerts are detected, so that the alert must be fixed or dismissed before the code change is merged. For more information about severity levels, see "[About alert severity and security severity levels](/code-security/code-scanning/managing-code-scanning-alerts/about-code-scanning-alerts#about-alert-severity-and-security-severity-levels)."

data/reusables/repositories/rulesets-require-code-scanning-results.md

@@ -0,0 +1,9 @@
+1. Under "Branch protections", select **Require {% data variables.product.prodname_code_scanning %} results**.
+1. Under "Required tools and alert thresholds", click **{% octicon "plus" aria-label="Add tool" %} Add tool** and select a {% data variables.product.prodname_code_scanning %} tool with the dropdown. For example, "{% data variables.product.prodname_codeql %}".
+1. Next to the name of a {% data variables.product.prodname_code_scanning %} tool:
+    - Click **Alerts** and select one of: **None**, **Errors**, **Errors and Warnings** or **All**.
+    - Click **Security alerts** and select one of: **None**, **Critical**, **High or higher**, **Medium or higher**, or **All**.
+
+    ![Screenshot of the "Required tools and alert thresholds" section of "Rulesets" settings.](/assets/images/help/repository/rulesets-require-code-scanning.png)
+
+For more information about alert severity and security severity levels, see "[AUTOTITLE](/code-security/code-scanning/managing-code-scanning-alerts/about-code-scanning-alerts#about-alert-severity-and-security-severity-levels)."