Code scanning: uploading results as PR checks (#18050)

Author: shati-patel

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

@@ -35,12 +35,18 @@ To customize the way the {% data variables.product.prodname_codeql_runner %} sca
 
 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.
+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
+$ /path/to-runner/codeql-runner-linux analyze --ref refs/pull/42/merge
 ```
 
+{% note %}
+
+**Note**: If you analyze code with a third-party tool and want the results to appear as pull request checks, you must run the `upload` command and use the `--ref` flag to specify the pull request instead of the branch. The reference is `refs/pull/<PR-number>/head` or `refs/pull/<PR-number>/merge`.
+
+{% endnote %}
+
 ### Overriding automatic language detection
 
 The {% data variables.product.prodname_codeql_runner %} automatically detects and scans code written in the supported languages.
@@ -110,7 +116,9 @@ If the `autobuild` command can't build your code, you can run the build steps yo
 
 By default, the {% data variables.product.prodname_codeql_runner %} uploads results from {% data variables.product.prodname_code_scanning %} when you run the `analyze` command. You can also upload SARIF files separately, by using the `upload` command.
 
-Once you've uploaded the data, {% data variables.product.prodname_dotcom %} displays the alerts in your repository. For more information, see "[Managing {% data variables.product.prodname_code_scanning %} alerts for your repository](/github/finding-security-vulnerabilities-and-errors-in-your-code/managing-code-scanning-alerts-for-your-repository#viewing-the-alerts-for-a-repository)."
+Once you've uploaded the data, {% data variables.product.prodname_dotcom %} displays the alerts in your repository. 
+- If you uploaded to a pull request, for example `--ref refs/pull/42/merge` or `--ref refs/pull/42/head`, then the results appear as alerts in a pull request check. For more information, see "[Triaging code scanning alerts in pull requests](/github/finding-security-vulnerabilities-and-errors-in-your-code/triaging-code-scanning-alerts-in-pull-requests)."
+- If you uploaded to a branch, for example `--ref refs/heads/my-branch`, then the results appear in the **Security** tab for your repository. For more information, see "[Managing code scanning alerts for your repository](/github/finding-security-vulnerabilities-and-errors-in-your-code/managing-code-scanning-alerts-for-your-repository#viewing-the-alerts-for-a-repository)."
 
 ### {% data variables.product.prodname_codeql_runner %} command reference
 

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

@@ -98,6 +98,8 @@ To view the command-line reference for the runner, use the `-h` flag. For exampl
 
 This example runs {% data variables.product.prodname_codeql %} analysis on a Linux CI server for the `octo-org/example-repo` repository hosted on `{% data variables.command_line.git_url_example %}`. The process is very simple because the repository contains only languages that can be analyzed by {% data variables.product.prodname_codeql %} directly, without being built (that is, Go, JavaScript, Python, and TypeScript).
 
+In this example, the server has access to download the {% data variables.product.prodname_codeql %} bundle directly from the `github/codeql-action` repository, so there is no need to use the `--codeql-path` flag.
+
 1. Check out the repository to analyze.
 1. Move into the directory where the repository is checked out.
 1. Initialize the {% data variables.product.prodname_codeql_runner %} and create {% data variables.product.prodname_codeql %} databases for the languages detected.
@@ -110,19 +112,7 @@ This example runs {% data variables.product.prodname_codeql %} analysis on a Lin
     > Created CodeQL database at /srv/checkout/example-repo/codeql-runner/codeql_databases/javascript.
     ```
 
-1. Populate the {% data variables.product.prodname_codeql_runner %} databases, analyze them, and upload the results to {% data variables.product.product_name %}.
-
-    ```shell
-    $ /path/to-runner/codeql-runner-linux analyze --repository octo-org/example-repo
-        --github-url {% data variables.command_line.git_url_example %} --github-auth TOKEN
-        --commit 5b6a3078b31dc346e5ce7b86837d6abbe7a18bbd --ref refs/heads/main
-    > Finalizing database creation
-    > ...
-    > POST /repos/octo-org/example-repo/code-scanning/sarifs - 202 in 786ms
-    > Successfully uploaded results
-    ```
-
-The server has access to download the {% data variables.product.prodname_codeql %} bundle directly from the `github/codeql-action` repository, so there is no need to use the `--codeql-path` flag. When the analysis is complete, the {% data variables.product.prodname_codeql_runner %} uploads the results to the {% data variables.product.prodname_code_scanning %} view. For more information, see "[Managing {% data variables.product.prodname_code_scanning %} alerts for your repository](/github/finding-security-vulnerabilities-and-errors-in-your-code/managing-code-scanning-alerts-for-your-repository)."
+{% data reusables.code-scanning.codeql-runner-analyze-example %}
 
 #### Compiled language example
 
@@ -139,8 +129,8 @@ This example is similar to the previous example, however this time the repositor
     > ...
     > CodeQL environment output to "/srv/checkout/example-repo-2/codeql-runner/codeql-env.json"
       and "/srv/checkout/example-repo-2/codeql-runner/codeql-env.sh".
-      Please export these variables to future processes so that CodeQL can monitor the build, for example by running "
-      . /srv/checkout/example-repo-2/codeql-runner/codeql-env.sh".
+      Please export these variables to future processes so that CodeQL can monitor the build, for example by running 
+      ". /srv/checkout/example-repo-2/codeql-runner/codeql-env.sh".
       ```
 
 1. Source the script generated by the `init` action to set up the environment to monitor the build. Note the leading dot and space in the following code snippet.
@@ -151,17 +141,7 @@ This example is similar to the previous example, however this time the repositor
 
 1. Build the code. On macOS, you need to prefix the build command with the environment variable `$CODEQL_RUNNER`. For more information, see "[Troubleshooting CodeQL code scanning in your CI system](/github/finding-security-vulnerabilities-and-errors-in-your-code/troubleshooting-codeql-code-scanning-in-your-ci-system#no-code-found-during-the-build)."
 
-1. Populate the {% data variables.product.prodname_codeql %} databases, analyze them, and upload the results to {% data variables.product.prodname_dotcom %}.
-
-    ```shell
-    $ /path/to-runner/codeql-runner-linux analyze --repository octo-org/example-repo-2
-        --github-url {% data variables.command_line.git_url_example %} --github-auth TOKEN
-        --commit ae7b655ef30b50fb726ae7b3daa79571a39d194d --ref refs/heads/main
-    > Finalizing database creation
-    > ...
-    > POST /repos/octo-org/example-repo-2/code-scanning/sarifs - 202 in 573ms
-    > Successfully uploaded results
-    ```
+{% data reusables.code-scanning.codeql-runner-analyze-example %}
 
 {% note %}
 

data/reusables/code-scanning/codeql-runner-analyze-example.md

@@ -0,0 +1,25 @@
+1. Populate the {% data variables.product.prodname_codeql %} databases, analyze them, and upload the results to {% data variables.product.product_name %}. The results will appear in the **Security** tab for your repository.
+
+    ```shell
+    $ /path/to-runner/codeql-runner-linux analyze --repository octo-org/example-repo
+        --github-url {% data variables.command_line.git_url_example %} --github-auth TOKEN
+        --commit 5b6a3078b31dc346e5ce7b86837d6abbe7a18bbd --ref refs/heads/my-branch
+    > Finalizing database creation
+    > ...
+    > POST /repos/octo-org/example-repo/code-scanning/sarifs - 202 in 786ms
+    > Successfully uploaded results
+    ```
+
+1. To upload {% data variables.product.prodname_code_scanning %} results as pull request checks, specify the pull request using the <nobr>`--ref`</nobr> flag. We recommend setting up the {% data variables.product.prodname_codeql_runner %} so that it runs on the [`pull_request`](/developers/webhooks-and-events/webhook-events-and-payloads#pull_request) webhook event.
+
+    ```shell
+    $ /path/to-runner/codeql-runner-linux analyze --repository octo-org/example-repo
+        --github-url {% data variables.command_line.git_url_example %} --github-auth TOKEN
+        --commit 1dc7a1346e5ce7b86835b68bbda3078b37d6abbe --ref refs/pull/123/merge
+    > Finalizing database creation
+    > ...
+    > POST /repos/octo-org/example-repo/code-scanning/sarifs - 202 in 786ms
+    > Successfully uploaded results
+    ```
+
+For more information about viewing {% data variables.product.prodname_code_scanning %} alerts, see "[Triaging code scanning alerts in pull requests](/github/finding-security-vulnerabilities-and-errors-in-your-code/triaging-code-scanning-alerts-in-pull-requests)" and "[Managing code scanning alerts for your repository](/github/finding-security-vulnerabilities-and-errors-in-your-code/managing-code-scanning-alerts-for-your-repository)."