CodeQL: static analysis on the pull request, not in a weekly digest

.github/workflows/codeql.yml

@@ -0,0 +1,46 @@
+name: CodeQL
+
+# Static analysis on every pull request, so a finding arrives while the change is still being
+# read rather than in a weekly digest nobody opens. `security-and-quality` rather than the
+# default suite: this is a small codebase in the execution path of consequential actions, and
+# the extra queries cost a few minutes that a project this size can afford.
+#
+# Findings land in the repository's code-scanning tab. Nothing here gates a merge -- the
+# required checks stay `check (3.11)`, `check (3.12)` and `package` -- because a static
+# analyser's first run on an unfamiliar codebase is a reading list, not a verdict.
+
+on:
+  pull_request:
+  push:
+    branches: [main]
+  schedule:
+    - cron: "41 5 * * 1"
+
+permissions:
+  contents: read
+
+jobs:
+  analyze:
+    name: Analyze Python
+    runs-on: ubuntu-latest
+    timeout-minutes: 20
+    permissions:
+      security-events: write # to upload the findings to code scanning
+      contents: read
+
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+
+      - uses: github/codeql-action/init@cdf488f595d80d6e07e03d4674febd5ab45fa938 # v4.37.9
+        with:
+          languages: python
+          # The core is stdlib plus pyyaml and click, and every extra is imported lazily, so
+          # there is nothing to build and nothing to install for the analyser to see the code.
+          build-mode: none
+          queries: security-and-quality
+
+      - uses: github/codeql-action/analyze@cdf488f595d80d6e07e03d4674febd5ab45fa938 # v4.37.9
+        with:
+          category: "/language:python"

tests/test_repository_signals.py

@@ -137,6 +137,34 @@ def test_the_scorecard_workflow_publishes_and_the_readme_shows_it():
     assert "api.scorecard.dev/projects/github.com/CTRLRun/ctrlrun/badge" in readme
 
 
+def test_codeql_analyses_every_pull_request():
+    """Static analysis that runs on a schedule alone reports findings against code that was
+    merged a week ago. This asserts it runs on the pull request, covers the language the
+    project is written in, and can write its findings somewhere a person will see them."""
+    workflow = _workflow("codeql.yml")
+    triggers = workflow[True] if True in workflow else workflow["on"]
+    assert "pull_request" in triggers, "findings would arrive after the merge"
+    assert "schedule" in triggers, "a new query release should reach old code"
+
+    job = workflow["jobs"]["analyze"]
+    assert workflow["permissions"] == {"contents": "read"}
+    assert job["permissions"]["security-events"] == "write"
+    assert job["timeout-minutes"] <= 30, "an analysis that can hang is a queue nobody clears"
+
+    init = next(s for s in job["steps"] if "codeql-action/init" in str(s.get("uses", "")))
+    assert init["with"]["languages"] == "python"
+    assert "codeql-action/analyze" in "".join(str(s.get("uses", "")) for s in job["steps"])
+
+
+def test_codeql_does_not_gate_a_merge():
+    """Deliberate, and recorded here so it is a decision rather than an oversight: a static
+    analyser's first run on an unfamiliar codebase is a reading list, not a verdict. The
+    required checks stay the three that were already required, and the workflow's own comment
+    says so -- if that changes, this test is where the argument gets rewritten."""
+    workflow = (WORKFLOWS / "codeql.yml").read_text(encoding="utf-8")
+    assert "Nothing here gates a merge" in workflow
+
+
 # --- community files -----------------------------------------------------------------------