Update information on SARIF results upload for user feedback (#37610)

Co-authored-by: Henning Makholm <[email protected]> Co-authored-by: Henry Mercer <[email protected]> Co-authored-by: Ben Ahmady <[email protected]>
witaliy12 · Jun 13, 2023 · 4825012 · 4825012
1 parent 9d9fcc2
commit 4825012
Showing 1 changed file with 25 additions and 14 deletions.
diff --git a/...anning-with-your-existing-ci-system/configuring-codeql-cli-in-your-ci-system.md b/...anning-with-your-existing-ci-system/configuring-codeql-cli-in-your-ci-system.md
@@ -201,17 +201,26 @@ $ codeql database analyze /codeql-dbs/example-repo \
 
 Before you can upload results to {% data variables.product.product_name %}, you must determine the best way to pass the {% data variables.product.prodname_github_app %} or {% data variables.product.pat_generic %} you created earlier to the {% data variables.product.prodname_codeql_cli %} (see [Installing {% data variables.product.prodname_codeql_cli %} in your CI system](/code-security/code-scanning/using-codeql-code-scanning-with-your-existing-ci-system/installing-codeql-cli-in-your-ci-system#generating-a-token-for-authentication-with-github)). We recommend that you review your CI system's guidance on the secure use of a secret store. The {% data variables.product.prodname_codeql_cli %} supports:
 
-- Passing the token to the CLI via standard input using the `--github-auth-stdin` option (recommended).
+- Interfacing with a secret store using the `--github-auth-stdin` option (recommended).
 - Saving the secret in the environment variable `GITHUB_TOKEN` and running the CLI without including the `--github-auth-stdin` option.
+- For testing purposes you can pass the `--github-auth-stdin` command-line option and supply a temporary token via standard input.
 
-When you have decided on the most secure and reliable method for your CI server, run `codeql github upload-results` on each SARIF results file and include `--github-auth-stdin` unless the token is available in the environment variable `GITHUB_TOKEN`.
+When you have decided on the most secure and reliable method for your CI server, run `codeql github upload-results` on each SARIF results file and include `--github-auth-stdin` unless the token is available in the environment variable `GITHUB_TOKEN`. 
 
 ```shell
-echo "$UPLOAD_TOKEN" | codeql github upload-results \
+# {% data variables.product.prodname_github_app %} or {% data variables.product.pat_generic %} available from a secret store
+&lt;call-to-retrieve-secret&gt; | codeql github upload-results \
     --repository=&lt;repository-name&gt; \
     --ref=&lt;ref&gt; --commit=&lt;commit&gt; \
     --sarif=&lt;file&gt; {% ifversion ghes or ghae %}--github-url=&lt;URL&gt; \
     {% endif %}--github-auth-stdin
+
+# {% data variables.product.prodname_github_app %} or {% data variables.product.pat_generic %} available in GITHUB_TOKEN
+codeql github upload-results \
+    --repository=&lt;repository-name&gt; \
+    --ref=&lt;ref&gt; --commit=&lt;commit&gt; \
+    --sarif=&lt;file&gt; {% ifversion ghes or ghae %}--github-url=&lt;URL&gt; \
+    {% endif %}
 ```
 
 | Option | Required | Usage |
@@ -221,20 +230,20 @@ echo "$UPLOAD_TOKEN" | codeql github upload-results \
 | <nobr>`--commit`</nobr> | {% octicon "check" aria-label="Required" %} | Specify the full SHA of the commit you analyzed.
 | <nobr>`--sarif`</nobr> | {% octicon "check" aria-label="Required" %} | Specify the SARIF file to load.{% ifversion ghes or ghae %}
 | <nobr>`--github-url`</nobr> | {% octicon "check" aria-label="Required" %} | Specify the URL for {% data variables.product.product_name %}.{% endif %}
-| <nobr>`--github-auth-stdin`</nobr> | {% octicon "x" aria-label="Optional" %}  | Use to pass the CLI the {% data variables.product.prodname_github_app %} or {% data variables.product.pat_generic %} created for authentication with {% data variables.product.company_short %}'s REST API via standard input. This is not needed if the command has access to a `GITHUB_TOKEN` environment variable set with this token.
+| <nobr>`--github-auth-stdin`</nobr> | {% octicon "x" aria-label="Optional" %}  | Pass the CLI the {% data variables.product.prodname_github_app %} or {% data variables.product.pat_generic %} created for authentication with {% data variables.product.company_short %}'s REST API from your secret store via standard input. This is not needed if the command has access to a `GITHUB_TOKEN` environment variable set with this token.
 
 For more information, see "[AUTOTITLE](/code-security/codeql-cli/codeql-cli-manual/github-upload-results)."
 
 ### Basic example of uploading results to {% data variables.product.product_name %}
 
-This example uploads results from the SARIF file `temp/example-repo-js.sarif` to the repository `my-org/example-repo`. It tells the {% data variables.product.prodname_code_scanning %} API that the results are for the commit `deb275d2d5fe9a522a0b7bd8b6b6a1c939552718` on the `main` branch.
+The following example uploads results from the SARIF file `temp/example-repo-js.sarif` to the repository `my-org/example-repo`. It tells the {% data variables.product.prodname_code_scanning %} API that the results are for the commit `deb275d2d5fe9a522a0b7bd8b6b6a1c939552718` on the `main` branch. The example assumes that the {% data variables.product.prodname_github_app %} or {% data variables.product.pat_generic %} created for authentication with {% data variables.product.company_short %}'s REST API uses the `GITHUB_TOKEN` environment variable.
 
 ```
-$ echo $UPLOAD_TOKEN | codeql github upload-results \
+codeql github upload-results \
     --repository=my-org/example-repo \
     --ref=refs/heads/main --commit=deb275d2d5fe9a522a0b7bd8b6b6a1c939552718 \
     --sarif=/temp/example-repo-js.sarif {% ifversion ghes or ghae %}--github-url={% data variables.command_line.git_url_example %} \
-    {% endif %}--github-auth-stdin
+    {% endif %}
 ```
 
 There is no output from this command unless the upload was unsuccessful. The command prompt returns when the upload is complete and data processing has begun. On smaller codebases, you should be able to explore the {% data variables.product.prodname_code_scanning %} alerts in {% data variables.product.product_name %} shortly afterward. You can see alerts directly in the pull request or on the **Security** tab for branches, depending on the code you checked out. For more information, see "[AUTOTITLE](/code-security/code-scanning/automatically-scanning-your-code-for-vulnerabilities-and-errors/triaging-code-scanning-alerts-in-pull-requests)" and "[AUTOTITLE](/code-security/code-scanning/automatically-scanning-your-code-for-vulnerabilities-and-errors/managing-code-scanning-alerts-for-your-repository)."
@@ -266,11 +275,11 @@ This SARIF file will contain diagnostic information for the failed analysis, inc
 You can make this diagnostic information available on the tool status page by uploading the SARIF file to {% data variables.product.product_name %} using "[AUTOTITLE](/code-security/codeql-cli/codeql-cli-manual/github-upload-results)", for example:
 
 ```bash
-$ echo $UPLOAD_TOKEN | codeql github upload-results \
+codeql github upload-results \
     --repository=my-org/example-repo \
     --ref=refs/heads/main --commit=deb275d2d5fe9a522a0b7bd8b6b6a1c939552718 \
     --sarif=/temp/example-repo-js.sarif {% ifversion ghes or ghae %}--github-url={% data variables.command_line.git_url_example %} \
-    {% endif %}--github-auth-stdin
+    {% endif %}
 ```
 
 This is the same as the process for uploading SARIF files from successful analyses.
@@ -288,7 +297,7 @@ Before you can use a {% data variables.product.prodname_codeql %} pack to analyz
 | Option | Required | Usage |
 |--------|:--------:|-----|
 | <nobr>`<scope/name@version:path>`</nobr> | {% octicon "check" aria-label="Required" %} | Specify the scope and name of one or more CodeQL query packs to download using a comma-separated list. Optionally, include the version to download and unzip. By default the latest version of this pack is downloaded. Optionally, include a path to a query, directory, or query suite to run. If no path is included, then run the default queries of this pack. |
-| <nobr>`--github-auth-stdin`</nobr> | {% octicon "x" aria-label="Optional" %}  | Pass the {% data variables.product.prodname_github_app %} or {% data variables.product.pat_generic %} created for authentication with {% data variables.product.company_short %}'s REST API to the CLI via standard input. This is not needed if the command has access to a `GITHUB_TOKEN` environment variable set with this token.
+| <nobr>`--github-auth-stdin`</nobr> | {% octicon "x" aria-label="Optional" %}  | Pass the CLI the {% data variables.product.prodname_github_app %} or {% data variables.product.pat_generic %} created for authentication with {% data variables.product.company_short %}'s REST API from your secret store via standard input. This is not needed if the command has access to a `GITHUB_TOKEN` environment variable set with this token.
 
 {% ifversion query-pack-compatibility %}
 {% note %}
@@ -367,18 +376,20 @@ codeql database analyze codeql-dbs/python python-code-scanning.qls \
     --format=sarif-latest --sarif-category=python --output=python-results.sarif
 
 # Upload the SARIF file with the Java results: 'java-results.sarif'
+# The {% data variables.product.prodname_github_app %} or {% data variables.product.pat_generic %} created for authentication 
+# with {% data variables.product.company_short %}'s REST API is available in the `GITHUB_TOKEN` environment variable.
 
-echo $UPLOAD_TOKEN | codeql github upload-results \
+codeql github upload-results \
     --repository=my-org/example-repo \
     --ref=refs/heads/main --commit=deb275d2d5fe9a522a0b7bd8b6b6a1c939552718 \
-    --sarif=java-results.sarif --github-auth-stdin
+    --sarif=java-results.sarif
 
 # Upload the SARIF file with the Python results: 'python-results.sarif'
 
-echo $UPLOAD_TOKEN | codeql github upload-results \
+codeql github upload-results \
     --repository=my-org/example-repo \
     --ref=refs/heads/main --commit=deb275d2d5fe9a522a0b7bd8b6b6a1c939552718 \
-    --sarif=python-results.sarif --github-auth-stdin
+    --sarif=python-results.sarif
 ```
 
 ## Troubleshooting the {% data variables.product.prodname_codeql_cli %} in your CI system