Code Scanning/CodeQL: Add docs for supported repository properties (#60138)

Co-authored-by: Ben Ahmady <32935794+subatoi@users.noreply.github.com>
Co-authored-by: mc <42146119+mchammer01@users.noreply.github.com>

Author: 3 people

content/code-security/concepts/code-scanning/index.md

@@ -24,4 +24,5 @@ children:
   - /codeql
   - /tool-status-page
   - /pull-request-alert-metrics
+  - /repository-properties
 ---

content/code-security/concepts/code-scanning/repository-properties.md

@@ -0,0 +1,42 @@
+---
+title: Repository properties for {% data variables.product.prodname_code_scanning %}
+shortTitle: Repository properties
+intro: You can use repository properties to adjust {% data variables.product.prodname_code_scanning %} to suit your needs.
+topics:
+  - Code Security
+  - Code scanning
+versions:
+  feature: codeql-custom-properties
+contentType: concepts
+---
+
+## Prerequisites
+
+For the repository properties described here to have an effect, you need to have set up {% data variables.product.prodname_code_scanning %}. See [AUTOTITLE](/code-security/concepts/code-scanning/setup-types).
+
+Repository properties which affect {% data variables.product.prodname_code_scanning %} must be created manually for your organization. You can then set values for them that apply to your entire organization or allow them to be configured differently for each repository. See [AUTOTITLE](/organizations/managing-organization-settings/managing-custom-properties-for-repositories-in-your-organization).
+
+## Supported repository properties for {% data variables.product.prodname_code_scanning %}
+
+Some {% data variables.product.prodname_code_scanning %} functionality can be configured using repository properties. Organizations can use repository properties to both enforce configurations across all repositories and for individual repositories. If {% data variables.product.prodname_code_scanning %} is customized using repository properties, the customization applies to all setup types.
+
+The following is an overview of repository properties you can set up which affect {% data variables.product.prodname_code_scanning %} analyses when configured:
+
+| Name | Type |
+|------|------|
+| `github-codeql-extra-queries` | Text |
+| `github-codeql-disable-overlay` | True/false |
+| `github-codeql-file-coverage-on-prs` | True/false |
+
+> [!NOTE]
+> The repository properties which are supported depend on the version of the [github/codeql-action](https://github.com/github/codeql-action/) that is used by your {% data variables.product.prodname_code_scanning %} analyses. For {% data variables.product.prodname_code_scanning %} advanced setup, check that your workflow is referencing the latest major version. {% data variables.product.prodname_code_scanning_caps %} default setup automatically uses the latest version.{% ifversion ghes %} If the server on which you are running {% data variables.product.prodname_ghe_server %} is not connected to the internet, you may need to use the {% data variables.product.prodname_codeql %} action sync tool. See [AUTOTITLE](/code-security/how-tos/secure-at-scale/configure-enterprise-security/configure-specific-tools/configuring-code-scanning-for-your-appliance#configuring-codeql-analysis-on-a-server-without-internet-access).{% endif %}
+
+### Analysis customization
+
+The `github-codeql-extra-queries` property allows you to configure additional queries that should be run. This is useful to add queries to all relevant analyses in your organization without needing to modify individual workflows or switch to an advanced setup. This accepts the same values as the `queries` input of the [github/codeql-action](https://github.com/github/codeql-action/). See [AUTOTITLE](/code-security/reference/code-scanning/workflow-configuration-options).
+
+### Enabling or disabling features
+
+You can disable improved incremental analysis by setting the `github-codeql-disable-overlay` property to `true`. This may be useful if improved incremental analysis is failing because of increased hardware requirements.
+
+File coverage information is not calculated for analyses of pull requests. If you want to enable file coverage information for pull requests, you can set the `github-codeql-file-coverage-on-prs` property to `true`.

content/code-security/concepts/code-scanning/setup-types.md

@@ -30,8 +30,6 @@ If the code in a repository changes to include any {% data variables.product.pro
 
 After running an initial analysis of your code with default setup, you can make changes to your configuration to better meet your needs.
 
-If you need more granular control over your {% data variables.product.prodname_code_scanning %} configuration, you should instead configure advanced setup.
-
 ### Configuration options
 
 For existing configurations of default setup, you can edit:
@@ -42,6 +40,12 @@ For existing configurations of default setup, you can edit:
 
 If your codebase depends on a library or framework that is not recognized by the standard libraries included with {% data variables.product.prodname_codeql %}, you can also extend the {% data variables.product.prodname_codeql %} coverage in default setup using {% data variables.product.prodname_codeql %} model packs. For more information, see [Extending CodeQL coverage with CodeQL model packs in default setup](/code-security/how-tos/scan-code-for-vulnerabilities/manage-your-configuration/editing-your-configuration-of-default-setup#extending-codeql-coverage-with-codeql-model-packs-in-default-setup).
 
+{% ifversion codeql-custom-properties %}
+
+Additional configuration options that are shared between all {% data variables.product.prodname_code_scanning %} setup types are available. See [AUTOTITLE](/code-security/concepts/code-scanning/repository-properties).
+
+{% endif %}
+
 ### Available runners
 
 You can use default setup for all {% data variables.product.prodname_codeql %}-supported languages on self-hosted runners or {% data variables.product.prodname_dotcom %}-hosted runners.
@@ -60,7 +64,7 @@ Unless you have a specific use case, we recommend that you only assign runners w
 
 ## About advanced setup
 
-Advanced setup for {% data variables.product.prodname_code_scanning %} is helpful when you need to customize your {% data variables.product.prodname_code_scanning %}. You can set up {% data variables.product.prodname_code_scanning %} with {% data variables.product.prodname_actions %} or an external continuous integration or continuous delivery/deployment (CI/CD) system.
+If you need more granular control over your {% data variables.product.prodname_code_scanning %} configuration, you should instead configure advanced setup. Advanced setup for {% data variables.product.prodname_code_scanning %} is helpful when you need to customize your {% data variables.product.prodname_code_scanning %}. You can set up {% data variables.product.prodname_code_scanning %} with {% data variables.product.prodname_actions %} or an external continuous integration or continuous delivery/deployment (CI/CD) system.
 
 {% data reusables.code-scanning.about-multiple-configurations-link %}
 

content/code-security/how-tos/scan-code-for-vulnerabilities/configure-code-scanning/configuring-default-setup-for-code-scanning.md

@@ -71,6 +71,17 @@ Your repository is eligible for default setup for {% data variables.product.prod
    > [!NOTE]
    > If you are switching to default setup from advanced setup, you will see a warning informing you that default setup will override existing {% data variables.product.prodname_code_scanning %} configurations. This warning means default setup will disable the existing workflow file and block any {% data variables.product.prodname_codeql %} analysis API uploads.
 
+{% ifversion org-private-registry %}
+
+1. If projects in your repository depend on dependencies in private package registries, you can grant {% data variables.product.prodname_code_scanning %} access to them. This can improve the outcomes and quality of analyses. See [AUTOTITLE](/code-security/how-tos/secure-at-scale/configure-organization-security/manage-usage-and-access/giving-org-access-private-registries).
+
+{% endif %}
+{% ifversion codeql-custom-properties %}
+
+1. Optionally, adjust other configuration options which affect default setup. See [AUTOTITLE](/code-security/concepts/code-scanning/repository-properties).
+
+{% endif %}
+
 1. Optionally, to view your default setup configuration after enablement, select {% octicon "kebab-horizontal" aria-label="Menu" %}, then click **{% octicon "gear" aria-hidden="true" aria-label="gear" %} View {% data variables.product.prodname_codeql %} configuration**.
 
 > [!NOTE]

content/code-security/how-tos/scan-code-for-vulnerabilities/manage-your-configuration/editing-your-configuration-of-default-setup.md

@@ -15,9 +15,7 @@ redirect_from:
 contentType: how-tos
 ---
 
-After running an initial analysis of your code with default setup, you can make changes to your configuration to better meet your needs. For more information on setup types and customization options, see [AUTOTITLE](/code-security/concepts/code-scanning/setup-types).
-
-If you need to change any other aspects of your {% data variables.product.prodname_code_scanning %} configuration, consider configuring advanced setup. For more information, see [AUTOTITLE](/code-security/code-scanning/creating-an-advanced-setup-for-code-scanning/configuring-advanced-setup-for-code-scanning).
+After running an initial analysis of your code with default setup, you can make changes to your configuration to better meet your needs. See [AUTOTITLE](/code-security/concepts/code-scanning/setup-types){% ifversion codeql-custom-properties %} and [AUTOTITLE](/code-security/concepts/code-scanning/repository-properties){% endif %}.
 
 ## Customizing your existing configuration of default setup
 
@@ -90,3 +88,7 @@ For more information about {% data variables.product.prodname_codeql %} model pa
     ![Screenshot of the "Expand CodeQL analysis" view" in the settings for an organization.](/assets/images/help/security/enable-codeql-org-model-packs.png)
 
 1. The model packs will be automatically detected and used when {% data variables.product.prodname_code_scanning %} runs on any repository in the organization with default setup enabled.
+
+## Further customization
+
+If you need to change any other aspects of your {% data variables.product.prodname_code_scanning %} configuration, consider configuring advanced setup. See [AUTOTITLE](/code-security/code-scanning/creating-an-advanced-setup-for-code-scanning/configuring-advanced-setup-for-code-scanning).

data/features/codeql-custom-properties.yml

@@ -0,0 +1,5 @@
+# Allows the CodeQL Action to use repository properties.
+versions:
+  fpt: '*'
+  ghec: '*'
+  ghes: '>= 3.21'