codeql-analysis.yml

name: "CodeQL"

on:
  push:
    branches: [main]
  # #2243, the owner's option B: a docs-only or test-only pull request skips
  # the scan. util/classify_changes.py's docs and tests, by docs.github.com's
  # "Avoiding unnecessary scans of pull requests"; the config leaves tests/ out
  # of the database anyway (#2130), so such a diff scans as its base does. A
  # path filter rather than the `changes` job, as no ruleset requires a check
  # of this workflow, so a run that never starts holds nothing pending. A
  # push and the schedule have no filter.
  pull_request:
    branches: [main]
    paths-ignore:
      - 'docs/**'
      - 'tests/**'
      - '**.md'
  schedule:
    - cron: '0 2 * * 6'

# #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
# `concurrency`): a ref-keyed group drops a *pending* run when a newer one
# joins, which here would leave a commit on main with no analysis on record.
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.
  analyze:
    name: Analyze
    runs-on: ubuntu-latest
    permissions:
      actions: read
      contents: read
      security-events: write

    steps:
    - name: Checkout repository
      uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1

    # #2130: the config leaves tests/ out of the scan.
    - name: Initialize CodeQL
      uses: github/codeql-action/init@9b3254085494b55a0f7c4c2b3d2d52cc712ce370 # v4.39.1
      with:
        config-file: ./.github/codeql/codeql-config.yml

    - name: Autobuild
      uses: github/codeql-action/autobuild@9b3254085494b55a0f7c4c2b3d2d52cc712ce370 # v4.39.1

    - name: Perform CodeQL Analysis
      uses: github/codeql-action/analyze@9b3254085494b55a0f7c4c2b3d2d52cc712ce370 # v4.39.1

  # #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 util/codeql_report.py and util/discussion_report.py.
  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"