You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: content/code-security/concepts/code-scanning/repository-properties.md
+33Lines changed: 33 additions & 0 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -15,6 +15,12 @@ For the repository properties described here to have an effect, you need to have
15
15
16
16
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).
17
17
18
+
## Testing changes before applying them
19
+
20
+
You may wish to test that configurations applied through repository properties have the desired effects before rolling them out to your entire organization. Repository properties can be set to specific values for individual repositories. If you are configuring a repository property for the first time, create it for your organization but do not set it to a value. Instead, set it to a value for a specific test repository where you can validate the change first. Once validated on a test repository, you can then set the value for your entire organization or the desired repositories.
21
+
22
+
When changing the value of a supported repository property, you can use the same approach. Override or set the value of the repository property for a test repository, validate the change, and then roll it out to your organization or other repositories.
23
+
18
24
## Supported repository properties for {% data variables.product.prodname_code_scanning %}
19
25
20
26
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.
@@ -23,17 +29,44 @@ The following is an overview of repository properties you can set up which affec
> 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 %}
32
44
45
+
{% ifversion codeql-config-property %}
46
+
47
+
### Custom configuration files
48
+
49
+
You can set the `github-codeql-config-file` property to the local or remote path of a configuration file. Accepted values for this property are the same as for the `config-file` parameter of the `codeql-action/init` action. For more information about accepted path formats and possible contents of configuration files, see [AUTOTITLE](/code-security/reference/code-scanning/workflow-configuration-options#custom-configuration-files).
50
+
51
+
A value specified for the `github-codeql-config-file` property will apply to both {% data variables.product.prodname_code_scanning %} default setup and {% data variables.product.prodname_code_scanning %} advanced setup. If an advanced setup workflow specifies an explicit input for the `config-file` parameter of the `codeql-action/init` action, then that input will take precedence over the value configured in the repository property. This allows advanced workflows to use different configurations than those applied to default setup workflows, if desired.
52
+
53
+
{% data reusables.code-scanning.config-file-merged-with-default-setup %} See [AUTOTITLE](/code-security/concepts/code-scanning/setup-types#configuration-options) for more information about available configuration options in {% data variables.product.prodname_code_scanning %} default setup.
54
+
55
+
### Other analysis customization
56
+
{% else %}
33
57
### Analysis customization
58
+
{% endif %}
34
59
35
60
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).
36
61
62
+
{% ifversion codeql-config-property %}
63
+
64
+
By default, {% data variables.product.prodname_code_scanning %} analyses use the latest released version of CodeQL. It is not generally recommended to change this, unless you are running into a specific issue that is resolved by switching to a different version. If you do need to change this, the `github-codeql-tools` property allows you to specify a different version.
65
+
66
+
If an advanced setup workflow specifies an explicit input for the `tools` parameter of the `codeql-action/init` action, then that input will take precedence over the value configured in the repository property. This allows advanced workflows to use different configurations than those applied to default setup workflows, if desired. To enforce the value of the repository property to advanced setup workflows even if they have an explicit `tools` input, add a `!` prefix to the value of the repository property. For example, `!nightly` enforces that all workflows use the latest `nightly` release.
67
+
68
+
{% endif %}
69
+
37
70
### Enabling or disabling features
38
71
39
72
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.
Copy file name to clipboardExpand all lines: content/code-security/concepts/code-scanning/setup-types.md
+8-2Lines changed: 8 additions & 2 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -13,7 +13,7 @@ category:
13
13
14
14
## About default setup
15
15
16
-
Default setup for {% data variables.product.prodname_code_scanning %} is the quickest, easiest, most low-maintenance way to enable {% data variables.product.prodname_code_scanning %} for your repository. Based on the code in your repository, default setup will automatically create a custom {% data variables.product.prodname_code_scanning %} configuration. After enabling default setup, the code written in {% data variables.product.prodname_codeql %}-supported languages in your repository will be scanned using {% data variables.product.prodname_codeql %}:
16
+
Default setup for {% data variables.product.prodname_code_scanning %} is the quickest, easiest, most low-maintenance way to enable {% data variables.product.prodname_code_scanning %} for your repository. Based on the code in your repository, default setup will automatically create a custom {% data variables.product.prodname_code_scanning %} configuration. You can also customize this configuration, including at scale across your organization, without creating or maintaining a workflow file. See [Customization of default setup](#customization-of-default-setup). After enabling default setup, the code written in {% data variables.product.prodname_codeql %}-supported languages in your repository will be scanned using {% data variables.product.prodname_codeql %}:
17
17
18
18
* On each push to the repository's default branch, or any protected branch. For more information on protected branches, see [AUTOTITLE](/repositories/configuring-branches-and-merges-in-your-repository/managing-protected-branches/about-protected-branches).
19
19
* When creating or committing to a pull request based against the repository's default branch, or any protected branch, excluding pull requests from forks.
@@ -39,6 +39,12 @@ For existing configurations of default setup, you can edit:
39
39
40
40
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/find-and-fix-code-vulnerabilities/manage-your-configuration/edit-default-setup#extending-codeql-coverage-with-codeql-model-packs-in-default-setup).
41
41
42
+
{% ifversion codeql-config-property %}
43
+
44
+
You can also apply a custom {% data variables.product.prodname_codeql %} configuration file to default setup across your organization at once, or for a single repository, by setting the `github-codeql-config-file` repository property. {% data reusables.code-scanning.config-file-merged-with-default-setup %} This lets you meet customization needs that previously required advanced setup, while keeping the low-maintenance benefits of default setup. See [AUTOTITLE](/code-security/concepts/code-scanning/repository-properties#custom-configuration-files) and [AUTOTITLE](/code-security/how-tos/find-and-fix-code-vulnerabilities/manage-your-configuration/edit-default-setup#customizing-default-setup-with-a-configuration-file).
45
+
46
+
{% endif %}
47
+
42
48
{% ifversion codeql-custom-properties %}
43
49
44
50
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).
@@ -59,7 +65,7 @@ Unless you have a specific use case, we recommend that you only assign runners w
59
65
60
66
## About advanced setup
61
67
62
-
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.
68
+
{% ifversion codeql-config-property %}If the customization options available for default setup, including a custom configuration file, don't meet your needs{% else %}If you need more granular control over your {% data variables.product.prodname_code_scanning %} configuration{% endif %}, you should instead configure advanced setup. Advanced setup for {% data variables.product.prodname_code_scanning %} is helpful when you need to define your own {% data variables.product.prodname_actions %} workflow, for example to build compiled languages, use a matrix build, or change the analysis schedule. 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.
63
69
64
70
{% data reusables.code-scanning.about-multiple-configurations-link %}
Copy file name to clipboardExpand all lines: content/code-security/how-tos/find-and-fix-code-vulnerabilities/manage-your-configuration/edit-default-setup.md
+34-1Lines changed: 34 additions & 1 deletion
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -16,7 +16,7 @@ category:
16
16
- Find and fix code vulnerabilities
17
17
---
18
18
19
-
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 %}.
19
+
After running an initial analysis of your code with default setup, you can make changes to your configuration to better meet your needs. You can customize your configuration in the user interface{% ifversion codeql-custom-properties %}, or using repository properties to add custom queries{% ifversion codeql-config-property %} or apply a custom configuration file{% endif %}{% endif %}. See [AUTOTITLE](/code-security/concepts/code-scanning/setup-types){% ifversion codeql-custom-properties %} and [AUTOTITLE](/code-security/concepts/code-scanning/repository-properties){% endif %}.
20
20
21
21
## Customizing your existing configuration of default setup
22
22
@@ -83,6 +83,39 @@ For more information about {% data variables.product.prodname_codeql %} model pa
83
83
84
84
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.
85
85
86
+
{% ifversion codeql-config-property %}
87
+
88
+
## Customizing default setup with a configuration file
89
+
90
+
You can further customize default setup by applying a {% data variables.product.prodname_codeql %} configuration file, using the `github-codeql-config-file` repository property. The configuration in the file is merged with the configuration default setup generates automatically, so you can, for example, add extra queries or exclude paths without needing to switch to advanced setup. For more information about what you can configure in a {% data variables.product.prodname_codeql %} configuration file, and how it's merged with default setup, see [AUTOTITLE](/code-security/concepts/code-scanning/repository-properties#custom-configuration-files).
91
+
92
+
### Applying a configuration file to all repositories in an organization
93
+
94
+
The recommended way to customize default setup at scale is to set an organization-wide default value for the `github-codeql-config-file` repository property, so that you don't need to update individual repositories as you add more of them to your organization.
95
+
96
+
1. Create a {% data variables.product.prodname_codeql %} configuration file in a central repository. You can either create a new repository for this purpose or add the file to an existing one. Your organization-wide configuration can then be maintained in one place. For information about the format of the configuration files, see [AUTOTITLE](/code-security/reference/code-scanning/workflow-configuration-options#custom-configuration-files).
97
+
98
+
{% data reusables.code-scanning.remote-config-file-registry %}
99
+
100
+
1. Create a `github-codeql-config-file` repository property for your organization and set its default value to the path of the configuration file. For example, if you have committed your configuration file as `codeql.yml` to the `main` branch of `octo-org/config`, you would set the value of the repository property to `remote=octo-org/config@main:codeql.yml`.
101
+
102
+
We recommend testing the configuration file on a single repository before setting the organization-wide default. See [AUTOTITLE](/code-security/concepts/code-scanning/repository-properties#testing-changes-before-applying-them).
103
+
104
+
1. The configuration file will be automatically detected and merged with the configuration default setup generates the next time {% data variables.product.prodname_code_scanning %} runs on each repository in the organization. Repositories that already have an explicit value set for the `github-codeql-config-file` property continue to use that value instead of the organization-wide default. For more information about how default and explicit repository property values interact, see [AUTOTITLE](/organizations/managing-organization-settings/managing-custom-properties-for-repositories-in-your-organization#adding-custom-properties).
105
+
106
+
### Applying a configuration file to a repository
107
+
108
+
If you only need to customize default setup for a single repository, or to test a configuration before rolling it out to your organization, you can set the property directly on that repository instead.
109
+
110
+
1. Create a {% data variables.product.prodname_codeql %} configuration file. This can be a file within the repository being analyzed, or a file in a separate repository. For information about the format of the configuration files, see [AUTOTITLE](/code-security/reference/code-scanning/workflow-configuration-options#custom-configuration-files).
111
+
112
+
{% data reusables.code-scanning.remote-config-file-registry %}
113
+
114
+
1. Set the `github-codeql-config-file` repository property for the repository to the local or remote path of the configuration file. See [AUTOTITLE](/code-security/concepts/code-scanning/repository-properties#custom-configuration-files) for more information about acceptable values for this property, and [AUTOTITLE](/organizations/managing-organization-settings/managing-custom-properties-for-repositories-in-your-organization#setting-values-for-repositories-in-your-organization) for how to set a repository property value.
115
+
1. The configuration file will be automatically detected and merged with the configuration default setup generates the next time {% data variables.product.prodname_code_scanning %} runs on the repository.
Copy file name to clipboardExpand all lines: content/code-security/how-tos/secure-at-scale/configure-organization-security/configure-specific-tools/code-scanning-at-scale.md
+6Lines changed: 6 additions & 0 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -37,6 +37,12 @@ You can enable default setup for all eligible repositories in your organization.
37
37
38
38
Through your organization's security settings page, you can customize default setup for all eligible repositories, such as extending coverage using model packs. See [AUTOTITLE](/code-security/how-tos/find-and-fix-code-vulnerabilities/manage-your-configuration/edit-default-setup).
39
39
40
+
{% ifversion codeql-config-property %}
41
+
42
+
You can also apply a custom {% data variables.product.prodname_codeql %} configuration file across your organization by requiring the `github-codeql-config-file` repository property for your organization and setting its default value. This lets you customize analysis at scale without maintaining workflow files. See [AUTOTITLE](/code-security/how-tos/find-and-fix-code-vulnerabilities/manage-your-configuration/edit-default-setup#applying-a-configuration-file-to-all-repositories-in-an-organization) for step-by-step instructions.
43
+
44
+
{% endif %}
45
+
40
46
## Configuring default setup for a subset of repositories in an organization
41
47
42
48
You can filter for specific repositories you would like to configure default setup for. For more information, see [AUTOTITLE](/code-security/how-tos/secure-at-scale/configure-organization-security/establish-complete-coverage/apply-custom-configuration).
Copy file name to clipboardExpand all lines: content/code-security/how-tos/secure-at-scale/configure-organization-security/manage-usage-and-access/giving-org-access-private-registries.md
+6Lines changed: 6 additions & 0 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -30,6 +30,12 @@ When you configure access to the private registries used in your organization, {
30
30
| Go | GOPROXY server, Git Source |
31
31
| Java | Maven Repository |
32
32
33
+
{% ifversion codeql-config-property %}
34
+
35
+
Additionally, _Git Source_ registries are supported for granting {% data variables.product.prodname_code_scanning %} access to configuration files in private repositories. For more information about customizing {% data variables.product.prodname_code_scanning %} using custom configuration files, see [AUTOTITLE](/code-security/reference/code-scanning/workflow-configuration-options#custom-configuration-files).
36
+
37
+
{% endif %}
38
+
33
39
> [!TIP]
34
40
> You can define one of each type of registry for each organization. If the codebases in your organization use more than one registry of a given type, you should set up a unified access point or define access to the most important registry for the codebases in that organization.
0 commit comments