codeql.yml

# CodeQL static analysis.
#
# Free here because the repository is public — CodeQL requires a GitHub Advanced Security
# licence only on private repositories.
#
# TWO languages, and the second is the one usually forgotten:
#   python   the src/ and tests/ tree
#   actions  the workflow files themselves. This repo's workflows hold `packages: write` and a
#            GHCR-capable GITHUB_TOKEN, and .github/ci/verify-image.sh is a shell script they
#            execute. Adding CI without scanning CI is how an injection into a `run:` block
#            goes unnoticed — the workflows are the part holding the credentials.
name: CodeQL

on:
  push:
    branches: [main]
  pull_request:
    branches: [main]
  schedule:
    # Weekly. Not redundant with the push/PR triggers: CodeQL ships new queries, so code that
    # was clean when it landed can become a finding without anyone touching it. Sunday 04:17
    # UTC — an off-peak minute rather than :00, which is when everyone else's cron fires.
    - cron: "17 4 * * 0"

# Least privilege at the top level; the analyse job adds only what it needs.
permissions:
  contents: read

concurrency:
  group: ${{ github.workflow }}-${{ github.ref }}
  cancel-in-progress: true

jobs:
  analyze:
    name: Analyze (${{ matrix.language }})
    runs-on: ubuntu-latest
    permissions:
      # Required to upload the SARIF results to the Security tab.
      security-events: write
      contents: read
      actions: read

    strategy:
      fail-fast: false
      matrix:
        language: [python, actions]

    steps:
      # SHA-pinned with a trailing version comment, matching ci.yml and publish.yml. A mutable
      # tag on a third-party action is a supply chain hole — the tag can be repointed at any
      # commit after review, and this job holds `security-events: write`.
      - name: Checkout
        uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4.4.0

      - name: Initialize CodeQL
        uses: github/codeql-action/init@2892aa5e19bbd11bc0cff5427e3b750a04d9e3c2 # v4.38.2
        with:
          languages: ${{ matrix.language }}
          # security-and-quality is a superset of the default suite. This is a small codebase
          # and the extra queries are worth the runtime.
          queries: security-and-quality

      # No build step. CodeQL analyses Python from source without one, and installing the
      # project here would only add a way for the analysis to fail for reasons unrelated to the
      # code. ci.yml already gates the build and the install.
      - name: Perform CodeQL analysis
        uses: github/codeql-action/analyze@2892aa5e19bbd11bc0cff5427e3b750a04d9e3c2 # v4.38.2
        with:
          category: /language:${{ matrix.language }}