ci: post the CodeQL report to Discussions (#2030)

.github/workflows/codeql-analysis.yml

@@ -8,7 +8,7 @@ on:
   schedule:
     - cron: '0 2 * * 6'
 
-# #1968: no scopes by default. `analyze` declares the ones it needs.
+# #1968: no scopes by default. Each job declares the ones it needs.
 permissions: {}
 
 # Only pull-request runs may be superseded (see unit-tests.yml's
@@ -18,6 +18,11 @@ concurrency:
   group: codeql-${{ github.event_name == 'pull_request' && github.ref || github.run_id }}
   cancel-in-progress: ${{ github.event_name == 'pull_request' }}
 
+# #2030: one Discussions category holds every report with no pull request to
+# comment on, one thread per job.
+env:
+  REPORT_CATEGORY: CI reports
+
 jobs:
   # Not gated on Unit Tests: CodeQL reads the source, so its findings do not
   # depend on the tests passing, and a failing test would suppress the scan.
@@ -41,3 +46,53 @@ jobs:
 
     - name: Perform CodeQL Analysis
       uses: github/codeql-action/analyze@6f2ac81f5cd81fe351a197ba0b00d91d03cd2aee # v4.39.0
+
+  # #2030: the run's report, to its thread in Discussions. A pull request's run
+  # posts nothing: its findings belong to the pull request, and the alerts the
+  # report lists are the default branch's. The only job holding
+  # `security-events: read` or `discussions: write`, and it runs no project
+  # code but the two util/ scripts.
+  discussion:
+    name: Post the CodeQL report
+    needs: [ analyze ]
+    if: ${{ always() && github.event_name != 'pull_request' && needs.analyze.result != 'skipped' }}
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    continue-on-error: true
+    permissions:
+      contents: read
+      discussions: write
+      security-events: read
+
+    steps:
+    - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+      with:
+        persist-credentials: false
+
+    # The default branch's open alerts, by severity, after `Perform CodeQL
+    # Analysis` waited for its upload to be processed. `status` is `analyze`'s
+    # result where it did not succeed or the alerts could not be read, and
+    # otherwise `warning` while any alert is open, `success` at none.
+    - name: Write the report
+      id: report
+      continue-on-error: true
+      env:
+        GH_TOKEN: ${{ github.token }}
+        ANALYZE_RESULT: ${{ needs.analyze.result }}
+      run: python3 util/codeql_report.py --result "$ANALYZE_RESULT" --report report/codeql-report.md
+
+    # The schedule posts every run. A push posts as a push run: every run with
+    # an open alert, then once on the first run back at none. A report step
+    # that wrote no status leaves `analyze`'s result.
+    - name: Post the report to Discussions
+      continue-on-error: true
+      env:
+        GH_TOKEN: ${{ github.token }}
+        MODE: ${{ github.event_name == 'schedule' && 'scheduled' || 'push' }}
+        ANALYZE_RESULT: ${{ needs.analyze.result }}
+        REPORT_STATUS: ${{ steps.report.outputs.status }}
+      run: |
+        status="${REPORT_STATUS:-$ANALYZE_RESULT}"
+        python3 util/discussion_report.py --category "$REPORT_CATEGORY" \
+          --title 'codeql-analysis: CodeQL report' --report report/codeql-report.md \
+          --mode "$MODE" --status "$status"

docs/source/contributing/workflows.rst

@@ -1233,6 +1233,9 @@ does; each has tests under :file:`tests/project/` that run it.
      - No step: it is imported by the scripts that share its annotations, step
        outputs, job summary lines and logged runs (`#2047
        <https://github.com/JarryShaw/PyPCAPKit/issues/2047>`__).
+   * - :file:`util/codeql_report.py`
+     - ``Write the report`` in ``codeql-analysis.yml``'s ``discussion`` (see `CI
+       Reports`_).
 
 The summaries run on the image's ``/usr/bin/python3`` rather than the leg's
 interpreter, which may have failed to set up or be too broken to run anything, so
@@ -1352,6 +1355,22 @@ run it links with ``GITHUB_WORKFLOW``, so the post step sets ``Unit Tests`` for
 that one command. A push relay's concurrency group is its own run's, since a
 group cancels a pending run when a newer one joins it.
 
+``codeql-analysis.yml`` posts to ``codeql-analysis: CodeQL report``, as
+``scheduled`` on its ``schedule`` and ``push`` on a push to ``main``, and never on
+a pull request, whose findings belong to the pull request. Its ``discussion`` job
+runs after ``analyze`` and alone holds ``security-events: read``, beside
+``discussions: write`` and ``contents: read``. ``Write the report`` runs
+:file:`util/codeql_report.py`, which lists the default branch's open CodeQL alerts
+by severity, read through GitHub's `List code scanning alerts for a repository
+<https://docs.github.com/en/rest/code-scanning/code-scanning#list-code-scanning-alerts-for-a-repository>`__
+endpoint, and hands on the step output ``status`` that ``Post the report to
+Discussions`` passes as ``--status``. A ``success`` of ``analyze`` reports
+``warning`` while any alert is open and ``success`` at none, so every push run
+with an open alert posts and the first run back at none posts once; any other
+result of ``analyze`` stands. Where the alerts cannot be read, the step writes a
+warning, the report marks them unavailable, and ``analyze``'s result stands
+unchanged.
+
 .. _Action Pins:
 
 Action Pins (`#1968 <https://github.com/JarryShaw/PyPCAPKit/issues/1968>`__)

tests/project/test_actions_helper_2047.py

@@ -40,7 +40,7 @@
 ROOT = pathlib.Path(__file__).resolve().parents[2]
 HELPER = ROOT / 'util' / '_actions.py'
 #: The scripts that import the helper.
-SCRIPTS = ('apt_packages', 'classify_changes', 'coverage_report', 'leg_summary', 'pip_install',
+SCRIPTS = ('apt_packages', 'classify_changes', 'codeql_report', 'coverage_report', 'leg_summary', 'pip_install',
            'regenerate_samples', 'vendor_code_changed')
 #: The top-level modules the helper may import, each in Python 3.7's standard
 #: library: the running interpreter's :data:`sys.stdlib_module_names` would
@@ -50,6 +50,7 @@
 RUNS = {
     'apt_packages': (['--help'], {}),
     'classify_changes': ([], {'OWN_PR': 'false'}),
+    'codeql_report': (['--help'], {}),
     'coverage_report': (['--help'], {}),
     'leg_summary': (['ktlo'], {'LEG': 'Python 3.8 (KTLO, non-blocking)', 'STEPS': '{}'}),
     'pip_install': (['--help'], {}),