Code scanning: Using the CodeQL runner to scan PRs

Author: shati-patel

content/github/finding-security-vulnerabilities-and-errors-in-your-code/configuring-codeql-code-scanning-in-your-ci-system.md

@@ -30,6 +30,16 @@ There are three versions of the {% data variables.product.prodname_codeql_runner
 
 To customize the way the {% data variables.product.prodname_codeql_runner %} scans your code, you can use flags, such as `--languages` and `--queries`, or you can specify custom settings in a separate configuration file.
 
+### Scanning pull requests
+
+Scanning code whenever a pull request is created prevents developers from introducing new vulnerabilities and errors into the code.
+
+To scan a pull request, run the `analyze` command and use the `--ref` flag to specify the pull request. The reference is `refs/pull/<pr-number>/head` or `refs/pull/<pr-number>/merge`, depending on whether you have checked out the HEAD commit of the pull request branch or a merge commit with the base branch.
+
+```shell
+$ /path/to-runner/codeql-runner-linux analyze --ref refs/pull/42/head
+```
+
 ### Overriding automatic language detection
 
 The {% data variables.product.prodname_codeql_runner %} automatically detects and scans code written in the supported languages.
@@ -116,7 +126,7 @@ Initializes the {% data variables.product.prodname_codeql_runner %} and creates
 | `--queries` | | Comma-separated list of additional queries to run, in addition to the default suite of security queries. |
 | `--config-file` | | Path to custom configuration file. |
 | `--codeql-path` | | Path to a copy of the {% data variables.product.prodname_codeql %} CLI executable to use. By default, the {% data variables.product.prodname_codeql_runner %} downloads a copy. |
-| `--temp-dir` | | Directory where temporary files are stored. The default is _./codeql-runner_. |
+| `--temp-dir` | | Directory where temporary files are stored. The default is `./codeql-runner`. |
 | `--tools-dir` | | Directory where {% data variables.product.prodname_codeql %} tools and other files are stored between runs. The default is a subdirectory of the home directory. |
 | <nobr>`--checkout-path`</nobr> | | The path to the checkout of your repository. The default is the current working directory.  |
 | `--debug` | | None. Prints more verbose output. |
@@ -129,7 +139,7 @@ Attempts to build the code for the compiled languages C/C++, C#, and Java. For t
 | Flag | Required | Input value |
 | ---- |:--------:| ----------- |
 | `--language` | | The language to build. By default, the {% data variables.product.prodname_codeql_runner %} builds the compiled language with the most files. |
-| <nobr>`--temp-dir`</nobr> | | Directory where temporary files are stored. The default is _./codeql-runner_. |
+| <nobr>`--temp-dir`</nobr> | | Directory where temporary files are stored. The default is `./codeql-runner`. |
 | `--debug` | | None. Prints more verbose output. |
 | `-h`, `--help` | | None. Displays help for the command. |
 
@@ -141,7 +151,7 @@ Analyzes the code in the {% data variables.product.prodname_codeql %} databases
 | ---- |:--------:| ----------- |
 | `--repository` | ✓ | Name of the repository to analyze. |
 | `--commit` | ✓ | SHA of the commit to analyze. In Git and in Azure DevOps, this corresponds to the value of `git rev-parse HEAD`. In Jenkins, this corresponds to `$GIT_COMMIT`. |
-| `--ref` | ✓ | Name of the reference to analyze, for example `refs/heads/main`. In Git and in Jenkins, this corresponds to the value of `git symbolic-ref HEAD`. In Azure DevOps, this corresponds to `$(Build.SourceBranch)`. |
+| `--ref` | ✓ | Name of the reference to analyze, for example `refs/heads/main` or `refs/pull/42/merge`. In Git or in Jenkins, this corresponds to the value of `git symbolic-ref HEAD`. In Azure DevOps, this corresponds to `$(Build.SourceBranch)`. |
 | `--github-url` | ✓ | URL of the {% data variables.product.prodname_dotcom %} instance where your repository is hosted. |
 | `--github-auth` | ✓ | A {% data variables.product.prodname_github_apps %} token or personal access token. |
 | <nobr>`--checkout-path`</nobr> | | The path to the checkout of your repository. The default is the current working directory.  |
@@ -150,20 +160,26 @@ Analyzes the code in the {% data variables.product.prodname_codeql %} databases
 | `--ram` | | Amount of memory to use when running queries. The default is to use all available memory. |
 | <nobr>`--no-add-snippets`</nobr> | | None. Excludes code snippets from the SARIF output. |
 | `--threads` | | Number of threads to use when running queries. The default is to use all available cores. |
-| `--temp-dir` | | Directory where temporary files are stored. The default is _./codeql-runner_. |
+| `--temp-dir` | | Directory where temporary files are stored. The default is `./codeql-runner`. |
 | `--debug` | | None. Prints more verbose output. |
 | `-h`, `--help` | | None. Displays help for the command. |
 
 #### `upload`
 
 Uploads SARIF files to {% data variables.product.product_location %}.
 
+{% note %}
+
+**Note**: If you analyze code with the CodeQL runner, the `analyze` command uploads SARIF results by default. You can use the `upload` command to upload SARIF results that were generated by other tools.
+
+{% endnote %}
+
 | Flag | Required | Input value |
 | ---- |:--------:| ----------- |
 | `--sarif-file` | ✓ | SARIF file to upload, or a directory containing multiple SARIF files. |
 | `--repository` | ✓ | Name of the repository that was analyzed. |
 | `--commit` | ✓ | SHA of the commit that was analyzed. In Git and in Azure DevOps, this corresponds to the value of `git rev-parse HEAD`. In Jenkins, this corresponds to `$GIT_COMMIT`. |
-| `--ref` | ✓ | Name of the reference that was analyzed, for example `refs/heads/main`. In Git and in Jenkins, this corresponds to the value of `git symbolic-ref HEAD`. In Azure DevOps, this corresponds to `$(Build.SourceBranch)`. |
+| `--ref` | ✓ | Name of the reference that was analyzed, for example `refs/heads/main` or `refs/pull/42/merge`. In Git or in Jenkins, this corresponds to the value of `git symbolic-ref HEAD`. In Azure DevOps, this corresponds to `$(Build.SourceBranch)`. |
 | `--github-url` | ✓ | URL of the {% data variables.product.prodname_dotcom %} instance where your repository is hosted. |
 | `--github-auth` | ✓ | A {% data variables.product.prodname_github_apps %} token or personal access token. |
 | <nobr>`--checkout-path`</nobr> | | The path to the checkout of your repository. The default is the current working directory.  |