|
|
|
|
@@ -76,11 +76,8 @@ Using the `pull_request` trigger, configured to scan the pull request's merge co
|
|
|
|
|
|
|
|
|
|
{% ifversion fpt or ghec %}
|
|
|
|
|
|
|
|
|
|
{% note %}
|
|
|
|
|
|
|
|
|
|
**Note:** If your repository is configured with a merge queue, you need to include the `merge_group` event as an additional trigger for {% data variables.product.prodname_code_scanning %}. This will ensure that pull requests are also scanned when they are added to a merge queue. For more information, see "[AUTOTITLE](/repositories/configuring-branches-and-merges-in-your-repository/configuring-pull-request-merges/managing-a-merge-queue)."
|
|
|
|
|
|
|
|
|
|
{% endnote %}
|
|
|
|
|
> [!NOTE]
|
|
|
|
|
> If your repository is configured with a merge queue, you need to include the `merge_group` event as an additional trigger for {% data variables.product.prodname_code_scanning %}. This will ensure that pull requests are also scanned when they are added to a merge queue. For more information, see "[AUTOTITLE](/repositories/configuring-branches-and-merges-in-your-repository/configuring-pull-request-merges/managing-a-merge-queue)."
|
|
|
|
|
|
|
|
|
|
{% endif %}
|
|
|
|
|
|
|
|
|
|
@@ -99,11 +96,8 @@ on:
|
|
|
|
|
- '**/*.txt'
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
{% note %}
|
|
|
|
|
|
|
|
|
|
**Note:** `on:pull_request:paths-ignore` and `on:pull_request:paths` set conditions that determine whether the actions in the workflow will run on a pull request. They don't determine what files will be analyzed when the actions _are_ run. When a pull request contains any files that are not matched by `on:pull_request:paths-ignore` or `on:pull_request:paths`, the workflow runs the actions and scans all of the files changed in the pull request, including those matched by `on:pull_request:paths-ignore` or `on:pull_request:paths`, unless the files have been excluded. For information on how to exclude files from analysis, see "[Specifying directories to scan](#specifying-directories-to-scan)."
|
|
|
|
|
|
|
|
|
|
{% endnote %}
|
|
|
|
|
> [!NOTE]
|
|
|
|
|
> `on:pull_request:paths-ignore` and `on:pull_request:paths` set conditions that determine whether the actions in the workflow will run on a pull request. They don't determine what files will be analyzed when the actions _are_ run. When a pull request contains any files that are not matched by `on:pull_request:paths-ignore` or `on:pull_request:paths`, the workflow runs the actions and scans all of the files changed in the pull request, including those matched by `on:pull_request:paths-ignore` or `on:pull_request:paths`, unless the files have been excluded. For information on how to exclude files from analysis, see "[Specifying directories to scan](#specifying-directories-to-scan)."
|
|
|
|
|
|
|
|
|
|
For more information about using `on:pull_request:paths-ignore` and `on:pull_request:paths` to determine when a workflow will run for a pull request, see "[AUTOTITLE](/actions/using-workflows/workflow-syntax-for-github-actions#onpushpull_requestpull_request_targetpathspaths-ignore)."
|
|
|
|
|
|
|
|
|
|
@@ -111,11 +105,8 @@ For more information about using `on:pull_request:paths-ignore` and `on:pull_req
|
|
|
|
|
|
|
|
|
|
If you use the default {% data variables.code-scanning.codeql_workflow %}, the workflow will scan the code in your repository once a week, in addition to the scans triggered by events. To adjust this schedule, edit the `cron` value in the workflow. For more information, see "[AUTOTITLE](/actions/using-workflows/workflow-syntax-for-github-actions#onschedule)."
|
|
|
|
|
|
|
|
|
|
{% note %}
|
|
|
|
|
|
|
|
|
|
**Note**: {% data variables.product.prodname_dotcom %} only runs scheduled jobs that are in workflows on the default branch. Changing the schedule in a workflow on any other branch has no effect until you merge the branch into the default branch.
|
|
|
|
|
|
|
|
|
|
{% endnote %}
|
|
|
|
|
> [!NOTE]
|
|
|
|
|
> {% data variables.product.prodname_dotcom %} only runs scheduled jobs that are in workflows on the default branch. Changing the schedule in a workflow on any other branch has no effect until you merge the branch into the default branch.
|
|
|
|
|
|
|
|
|
|
### Example
|
|
|
|
|
|
|
|
|
|
@@ -138,15 +129,10 @@ This workflow scans:
|
|
|
|
|
|
|
|
|
|
## Specifying an operating system
|
|
|
|
|
|
|
|
|
|
{% note %}
|
|
|
|
|
|
|
|
|
|
**Notes**:
|
|
|
|
|
|
|
|
|
|
* Code scanning of Swift code uses macOS runners by default. {% ifversion fpt or ghec %}{% data variables.product.company_short %}-hosted macOS runners are more expensive than Linux and Windows runners, so you should consider only scanning the build step. For more information about configuring code scanning for Swift, see "[AUTOTITLE](/code-security/code-scanning/creating-an-advanced-setup-for-code-scanning/codeql-code-scanning-for-compiled-languages#considerations-for-building-swift)." For more information about pricing for {% data variables.product.company_short %}-hosted runners, see "[AUTOTITLE](/billing/managing-billing-for-github-actions/about-billing-for-github-actions)."{% endif %}
|
|
|
|
|
|
|
|
|
|
* {% data reusables.code-scanning.default-setup-swift-self-hosted-runners %}
|
|
|
|
|
|
|
|
|
|
{% endnote %}
|
|
|
|
|
> [!NOTE]
|
|
|
|
|
> * Code scanning of Swift code uses macOS runners by default. {% ifversion fpt or ghec %}{% data variables.product.company_short %}-hosted macOS runners are more expensive than Linux and Windows runners, so you should consider only scanning the build step. For more information about configuring code scanning for Swift, see "[AUTOTITLE](/code-security/code-scanning/creating-an-advanced-setup-for-code-scanning/codeql-code-scanning-for-compiled-languages#considerations-for-building-swift)." For more information about pricing for {% data variables.product.company_short %}-hosted runners, see "[AUTOTITLE](/billing/managing-billing-for-github-actions/about-billing-for-github-actions)."{% endif %}
|
|
|
|
|
>
|
|
|
|
|
> * {% data reusables.code-scanning.default-setup-swift-self-hosted-runners %}
|
|
|
|
|
|
|
|
|
|
If your code requires a specific operating system to compile, you can configure the operating system in your {% data variables.code-scanning.codeql_workflow %}. Edit the value of `jobs.analyze.runs-on` to specify the operating system for the machine that runs your {% data variables.product.prodname_code_scanning %} actions. {% ifversion ghes %}You specify the operating system by using an appropriate label as the second element in a two-element array, after `self-hosted`.{% else %}
|
|
|
|
|
|
|
|
|
|
@@ -299,11 +285,8 @@ In this example, the default queries will be run for Java, as well as the querie
|
|
|
|
|
|
|
|
|
|
To add one or more {% data variables.product.prodname_codeql %} query packs, add a `with: packs:` entry within the `uses: {% data reusables.actions.action-codeql-action-init %}` section of the workflow. Within `packs` you specify one or more packages to use and, optionally, which version to download. Where you don't specify a version, the latest version is downloaded. If you want to use packages that are not publicly available, you need to set the `GITHUB_TOKEN` environment variable to a secret that has access to the packages. For more information, see "[AUTOTITLE](/actions/security-guides/automatic-token-authentication)" and "[AUTOTITLE](/actions/security-guides/encrypted-secrets)."
|
|
|
|
|
|
|
|
|
|
{% note %}
|
|
|
|
|
|
|
|
|
|
**Note:** For workflows that generate {% data variables.product.prodname_codeql %} databases for multiple languages, you must instead specify the {% data variables.product.prodname_codeql %} query packs in a configuration file. For more information, see "[Specifying {% data variables.product.prodname_codeql %} query packs](#specifying-codeql-query-packs)" below.
|
|
|
|
|
|
|
|
|
|
{% endnote %}
|
|
|
|
|
> [!NOTE]
|
|
|
|
|
> For workflows that generate {% data variables.product.prodname_codeql %} databases for multiple languages, you must instead specify the {% data variables.product.prodname_codeql %} query packs in a configuration file. For more information, see "[Specifying {% data variables.product.prodname_codeql %} query packs](#specifying-codeql-query-packs)" below.
|
|
|
|
|
|
|
|
|
|
In the example below, `scope` is the organization or personal account that published the package. When the workflow runs, the four {% data variables.product.prodname_codeql %} query packs are downloaded from {% data variables.product.product_name %} and the default queries or query suite for each pack run:
|
|
|
|
|
* The latest version of `pack1` is downloaded and all default queries are run.
|
|
|
|
|
@@ -318,18 +301,10 @@ In the example below, `scope` is the organization or personal account that publi
|
|
|
|
|
packs: scope/pack1,scope/pack2@1.2.3,scope/pack3@~3.2.1,scope/pack4@4.5.6:path/to/queries
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
{% note %}
|
|
|
|
|
|
|
|
|
|
**Note:** If you specify a particular version of a query pack to use,
|
|
|
|
|
beware that the version you specify may eventually become too old to
|
|
|
|
|
be used efficiently by the default
|
|
|
|
|
{% data variables.product.prodname_codeql %} engine used by the
|
|
|
|
|
{% data variables.product.prodname_codeql %} action.
|
|
|
|
|
To ensure optimal performance, if you need to specify exact query pack versions, you should consider reviewing periodically whether the pinned version of the query pack needs to be moved forward.
|
|
|
|
|
|
|
|
|
|
For more information about pack compatibility, see "[AUTOTITLE](/code-security/codeql-cli/using-the-advanced-functionality-of-the-codeql-cli/publishing-and-using-codeql-packs#about-codeql-pack-compatibility)."
|
|
|
|
|
|
|
|
|
|
{% endnote %}
|
|
|
|
|
> [!NOTE]
|
|
|
|
|
> If you specify a particular version of a query pack to use, beware that the version you specify may eventually become too old to be used efficiently by the default {% data variables.product.prodname_codeql %} engine used by the {% data variables.product.prodname_codeql %} action. To ensure optimal performance, if you need to specify exact query pack versions, you should consider reviewing periodically whether the pinned version of the query pack needs to be moved forward.
|
|
|
|
|
>
|
|
|
|
|
> For more information about pack compatibility, see "[AUTOTITLE](/code-security/codeql-cli/using-the-advanced-functionality-of-the-codeql-cli/publishing-and-using-codeql-packs#about-codeql-pack-compatibility)."
|
|
|
|
|
|
|
|
|
|
### Downloading {% data variables.product.prodname_codeql %} packs from {% data variables.product.prodname_ghe_server %}
|
|
|
|
|
|
|
|
|
|
@@ -517,13 +492,9 @@ query-filters:
|
|
|
|
|
|
|
|
|
|
To find the id of a query, you can click the alert in the list of alerts in the **Security** tab. This opens the alert details page. The `Rule ID` field contains the query id. For more information about the alert details page, see "[AUTOTITLE](/code-security/code-scanning/managing-code-scanning-alerts/about-code-scanning-alerts#about-alert-details)."
|
|
|
|
|
|
|
|
|
|
{% tip %}
|
|
|
|
|
|
|
|
|
|
**Tips:**
|
|
|
|
|
* The order of the filters is important. The first filter instruction that appears after the instructions about the queries and query packs determines whether the queries are included or excluded by default.
|
|
|
|
|
* Subsequent instructions are executed in order and the instructions that appear later in the file take precedence over the earlier instructions.
|
|
|
|
|
|
|
|
|
|
{% endtip %}
|
|
|
|
|
> [!TIP]
|
|
|
|
|
> * The order of the filters is important. The first filter instruction that appears after the instructions about the queries and query packs determines whether the queries are included or excluded by default.
|
|
|
|
|
> * Subsequent instructions are executed in order and the instructions that appear later in the file take precedence over the earlier instructions.
|
|
|
|
|
|
|
|
|
|
You can find another example illustrating the use of these filters in the "[Example configuration files](#example-configuration-files)" section.
|
|
|
|
|
|
|
|
|
|
@@ -541,15 +512,10 @@ paths-ignore:
|
|
|
|
|
- '**/*.test.js'
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
{% note %}
|
|
|
|
|
|
|
|
|
|
**Note**:
|
|
|
|
|
|
|
|
|
|
* The `paths` and `paths-ignore` keywords, used in the context of the {% data variables.product.prodname_code_scanning %} configuration file, should not be confused with the same keywords when used for `on.<push|pull_request>.paths` in a workflow. When they are used to modify `on.<push|pull_request>` in a workflow, they determine whether the actions will be run when someone modifies code in the specified directories. For more information, see "[AUTOTITLE](/actions/using-workflows/workflow-syntax-for-github-actions#onpushpull_requestpull_request_targetpathspaths-ignore)."
|
|
|
|
|
* The filter pattern characters `?`, `+`, `[`, `]`, and `!` are not supported and will be matched literally.
|
|
|
|
|
* `**` characters can only be at the start or end of a line, or surrounded by slashes, and you can't mix `**` and other characters. For example, `foo/**`, `**/foo`, and `foo/**/bar` are all allowed syntax, but `**foo` isn't. However you can use single stars along with other characters, as shown in the example. You'll need to quote anything that contains a `*` character.
|
|
|
|
|
|
|
|
|
|
{% endnote %}
|
|
|
|
|
> [!NOTE]
|
|
|
|
|
> * The `paths` and `paths-ignore` keywords, used in the context of the {% data variables.product.prodname_code_scanning %} configuration file, should not be confused with the same keywords when used for `on.<push|pull_request>.paths` in a workflow. When they are used to modify `on.<push|pull_request>` in a workflow, they determine whether the actions will be run when someone modifies code in the specified directories. For more information, see "[AUTOTITLE](/actions/using-workflows/workflow-syntax-for-github-actions#onpushpull_requestpull_request_targetpathspaths-ignore)."
|
|
|
|
|
> * The filter pattern characters `?`, `+`, `[`, `]`, and `!` are not supported and will be matched literally.
|
|
|
|
|
> * `**` characters can only be at the start or end of a line, or surrounded by slashes, and you can't mix `**` and other characters. For example, `foo/**`, `**/foo`, and `foo/**/bar` are all allowed syntax, but `**foo` isn't. However you can use single stars along with other characters, as shown in the example. You'll need to quote anything that contains a `*` character.
|
|
|
|
|
|
|
|
|
|
For analysis where code is built, if you want to limit {% data variables.product.prodname_code_scanning %} to specific directories in your project, you must specify appropriate build steps in the workflow. The commands you need to use to exclude a directory from the build will depend on your build system. For more information, see "[AUTOTITLE](/code-security/code-scanning/creating-an-advanced-setup-for-code-scanning/codeql-code-scanning-for-compiled-languages#adding-build-steps-for-a-compiled-language)."
|
|
|
|
|
|
|
|
|
|
@@ -582,22 +548,17 @@ This step in a {% data variables.product.prodname_actions %} workflow file uses
|
|
|
|
|
|
|
|
|
|
You can use the same approach to specify any valid configuration options in the workflow file.
|
|
|
|
|
|
|
|
|
|
{% tip %}
|
|
|
|
|
|
|
|
|
|
**Tip:**
|
|
|
|
|
|
|
|
|
|
You can share one configuration across multiple repositories using {% data variables.product.prodname_actions %} variables. One benefit of this approach is that you can update the configuration in a single place without editing the workflow file.
|
|
|
|
|
|
|
|
|
|
In the following example, `vars.CODEQL_CONF` is a {% data variables.product.prodname_actions %} variable. Its value can be the contents of any valid configuration file. For more information, see "[AUTOTITLE](/actions/learn-github-actions/variables#defining-configuration-variables-for-multiple-workflows)."
|
|
|
|
|
|
|
|
|
|
```yaml
|
|
|
|
|
- uses: {% data reusables.actions.action-codeql-action-init %}
|
|
|
|
|
with:
|
|
|
|
|
languages: {% raw %}${{ matrix.language }}{% endraw %}
|
|
|
|
|
config: {% raw %}${{ vars.CODEQL_CONF }}{% endraw %}
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
{% endtip %}
|
|
|
|
|
> [!TIP]
|
|
|
|
|
> You can share one configuration across multiple repositories using {% data variables.product.prodname_actions %} variables. One benefit of this approach is that you can update the configuration in a single place without editing the workflow file.
|
|
|
|
|
>
|
|
|
|
|
> In the following example, `vars.CODEQL_CONF` is a {% data variables.product.prodname_actions %} variable. Its value can be the contents of any valid configuration file. For more information, see "[AUTOTITLE](/actions/learn-github-actions/variables#defining-configuration-variables-for-multiple-workflows)."
|
|
|
|
|
>
|
|
|
|
|
> ```yaml
|
|
|
|
|
> - uses: {% data reusables.actions.action-codeql-action-init %}
|
|
|
|
|
> with:
|
|
|
|
|
> languages: {% raw %}${{ matrix.language }}{% endraw %}
|
|
|
|
|
> config: {% raw %}${{ vars.CODEQL_CONF }}{% endraw %}
|
|
|
|
|
> ```
|
|
|
|
|
|
|
|
|
|
## Configuring {% data variables.product.prodname_code_scanning %} for compiled languages
|
|
|
|
|
|
|
|
|
|
|
Artur Kordowski