🌱 polish scorecard workflow for use as example workflow (#3969)

This updates the version comments, adds some explanatory comments,
and generally makes it better. The intent is to use this file as an example
for the Scorecard Action repo so it remains up-to-date.

Signed-off-by: Spencer Schrock <[email protected]>

.github/workflows/scorecard-analysis.yml

@@ -7,8 +7,6 @@ on:
   schedule:
     # Weekly on Saturdays.
     - cron:  '30 1 * * 6'
-#   pull_request:
-#     branches: [main]
 
 permissions: read-all
 
@@ -17,36 +15,42 @@ jobs:
     name: Scorecard analysis
     runs-on: ubuntu-latest
     permissions:
+      # Needed for Code scanning upload
       security-events: write
+      # Needed for GitHub OIDC token if publish_results is true
       id-token: write
 
     steps:
       - name: "Checkout code"
         uses: actions/checkout@b4ffde65f46336ab88eb53be808477a3936bae11 # v4.1.1
+        with:
+          persist-credentials: false
 
       - name: "Run analysis"
         uses: ossf/scorecard-action@0864cf19026789058feabb7e87baa5f140aac736 # v2.3.1
         with:
           results_file: results.sarif
           results_format: sarif
-          repo_token: ${{ secrets.GITHUB_TOKEN }}
           # Scorecard team runs a weekly scan of public GitHub repos,
           # see https://github.com/ossf/scorecard#public-data.
           # Setting `publish_results: true` helps us scale by leveraging your workflow to
           # extract the results instead of relying on our own infrastructure to run scans.
           # And it's free for you!
           publish_results: true
 
+      # Upload the results as artifacts (optional). Commenting out will disable
+      # uploads of run results in SARIF format to the repository Actions tab.
       # https://docs.github.com/en/actions/advanced-guides/storing-workflow-data-as-artifacts
-      # Optional.
       - name: "Upload artifact"
-        uses: actions/upload-artifact@5d5d22a31266ced268874388b861e4b58bb5c2f3 # v3
+        uses: actions/upload-artifact@5d5d22a31266ced268874388b861e4b58bb5c2f3 # v4.3.1
         with:
           name: SARIF file
           path: results.sarif
           retention-days: 5
 
-      - name: "Upload SARIF results"
-        uses: github/codeql-action/upload-sarif@cdcdbb579706841c47f7063dda365e292e5cad7a # v1
+      # Upload the results to GitHub's code scanning dashboard (optional).
+      # Commenting out will disable upload of results to your repo's Code Scanning dashboard
+      - name: "Upload to code-scanning"
+        uses: github/codeql-action/upload-sarif@83a02f7883b12e0e4e1a146174f5e2292a01e601 # v2.16.4
         with:
           sarif_file: results.sarif