codeql.yml

name: CodeQL

# Static application security testing (SAST) for the Python code.
# Free for public repositories; results land under Security → Code scanning.
#
# Dependabot PRs are exempt from the analysis itself: dependency bumps don't
# change first-party code, and Dependabot-triggered runs get a read-only token
# that cannot upload SARIF (the analyze step would always fail). The job still
# reports success so the required `analyze` check doesn't block auto-merge.

on:
  push:
    branches: [main]
  pull_request:
    branches: [main]
  schedule:
    - cron: "30 5 * * 1" # weekly, Monday 05:30 UTC

permissions:
  contents: read

jobs:
  analyze:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      security-events: write
    steps:
      - name: Skip analysis for Dependabot PRs
        if: github.actor == 'dependabot[bot]'
        run: echo "Dependency bump — no first-party code change. CodeQL runs on main and weekly."

      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
        if: github.actor != 'dependabot[bot]'

      - name: Initialize CodeQL
        if: github.actor != 'dependabot[bot]'
        uses: github/codeql-action/init@54f647b7e1bb85c95cddabcd46b0c578ec92bc1a # v4.36.3
        with:
          languages: python
          # Security queries only. The "security-and-quality" suite also runs
          # maintainability/style queries that produce low-value "note" findings
          # (unused-global false positives, import-style nits) — noise for a
          # security gate, and a source of needless alert emails.
          queries: security-extended

      - name: Perform CodeQL analysis
        if: github.actor != 'dependabot[bot]'
        uses: github/codeql-action/analyze@8aad20d150bbac5944a9f9d289da16a4b0d87c1e # v4.36.2