codeql.yml

name: CodeQL

# Deep semantic SAST (taint / data-flow analysis) that complements bandit and the curated semgrep
# rules in security.yml — it finds vulnerable flows those pattern matchers can't, e.g. untrusted
# HL7/config data reaching a sink across function boundaries.
#
# WHY THIS IS GUARDED TO THE REPO SLUG: CodeQL uploads results to GitHub code scanning, which on a
# PRIVATE repo requires paid GitHub Advanced Security (see security.yml's header note). THIS repo is
# PUBLIC, so CodeQL + code scanning are FREE here. The analyze job is gated on the slug so it stays a
# skipped no-op anywhere the upload would fail or be billed — a fork, or the retired private archive.
#
# (Pre-cutover this described MEFORORG as "the OSS mirror" of a private source repo, and said the job
# ran "once publish.ps1 mirrors this file". Both premises are gone: MEFORORG is the source, and the
# publish machinery was deleted. The GUARD was already right — only its rationale had rotted.)
#
# PINNING: this repo SHA-pins every Action for supply-chain integrity, and every step below is
# pinned -- actions/checkout at v7.0.1, both github/codeql-action steps at v4.37.8. An earlier
# version of this note said the codeql-action steps were "on the v3 tag for now" and asked a reader
# to SHA-pin them "before treating this as a hardened gate". That was true when written and has been
# false since they were pinned; it was corrected 2026-09-01. Bumping a pin can change action
# behaviour, so re-read the action's inputs at the new SHA rather than trusting the notes below.
#
# ALTERNATIVE (no file): you can instead enable CodeQL "default setup" from
# Settings -> Security -> Code scanning (one toggle, auto-pinned, auto-updated). Default setup and this
# advanced workflow are mutually exclusive — if you turn default setup ON, delete this file.
on:
  # BACKLOG #340. Without this trigger CodeQL never reports on a merge_group event, so any CodeQL
  # context that is required would leave a queued pull request waiting forever on a check that
  # cannot arrive. Measured 2026-08-27 on the first entry the queue ever held: PR 619 sat
  # AWAITING_CHECKS with 32 check-runs green on gh-readonly-queue/main/pr-619-bca93ee1 and exactly
  # three contexts absent -- CodeQL, CodeQL (python), CodeQL (javascript-typescript).
  #
  # WHETHER THOSE CONTEXTS ARE REQUIRED IS DELIBERATELY NOT RECORDED HERE.
  # .github/required-contexts.txt mirrors the server and is the single authority; restating the
  # required set in a second file is how the two drift. An earlier version of this comment asserted
  # "THE QUEUE IS LIVE AND THESE THREE CONTEXTS ARE REQUIRED". That was true when written and is
  # false as of 2026-09-01, when the required set is 14 contexts and none of them is CodeQL
  # (BACKLOG #1404 records the removal). The trigger stays either way: it costs nothing while they
  # are not required, and it is the prerequisite that has to be in place BEFORE they ever are.
  #
  # security.yml's own on: block predicted this in the PR that added merge_group to the other
  # four workflows: "the failure mode of the reverse order is total -- enable a queue while a
  # required context's workflow has no merge_group trigger and that check never reports in the
  # queue, so NOTHING MERGES." codeql.yml was not among those four.
  merge_group:
  push:
    branches: [main]
  pull_request:
    branches: [main]
  schedule:
    # Weekly, so newly-shipped CodeQL queries run against unchanged code (same rationale as the daily
    # pip-audit cron: a fresh finding against a quiet codebase shouldn't wait for the next push).
    - cron: "0 7 * * 1"
  workflow_dispatch:

concurrency:
  # security.yml's pattern, and its note there is the reasoning: per-ref for PR events so a rapid
  # re-push supersedes its own in-flight analysis; every other event gets a unique group (run_id) and
  # is never superseded, never cancelled. THE `merge_group` ARM IS WHY THE EXPRESSION IS SHAPED THIS
  # WAY RATHER THAN `cancel-in-progress: true`: a cancelled queue-time run reports a cancelled
  # context, and the `on:` note above records what an absent CodeQL context did to the queue's first
  # entry. A unique group per non-PR run cannot collide, so it cannot be cancelled by this block.
  group: codeql-${{ github.event_name == 'pull_request' && github.ref || github.run_id }}
  cancel-in-progress: ${{ github.event_name == 'pull_request' }}

permissions:
  contents: read

jobs:
  analyze:
    name: CodeQL (${{ matrix.language }})
    # ONLY on this repo -- it is public, so code scanning is free; anywhere else (a fork's own
    # pushes, or the retired private archive) it would need paid GHAS, so this stays a skipped no-op
    # there. (GitHub Actions string == is case-insensitive.)
    #
    # THIS GUARD DOES NOT SKIP A FORK PULL REQUEST OPENED AGAINST THIS REPO. A pull_request run
    # executes in the BASE repository's context, so github.repository is 'MEFORORG/MessageFoundry'
    # and the guard is true. What it excludes is a fork pushing to its OWN branches, which gates
    # nothing here. ci.yml relies on exactly this reasoning for its required `test` contexts. So the
    # guard is not a fork problem and needs no change; see the Analyze step below for the measured
    # fork-upload finding.
    # AND NOT IN THE MERGE QUEUE, because the answer there is discarded. CodeQL is not a required
    # context (see .github/required-contexts.txt), so nothing waits on this result and nothing is
    # blocked by it, while the same tree is already analysed on the pull_request run and again on
    # the push to main after the entry lands. The merge-group pass is a third analysis nobody reads.
    #
    # THE COMMENT ON THE TRIGGER ABOVE SAYS THIS COSTS NOTHING WHILE THEY ARE NOT REQUIRED. That was
    # true about MINUTES and false about SLOTS. Measured 2026-09-07: MEFORORG is on the `free` plan,
    # whose ceiling is 20 concurrent jobs for the whole account, and a probe caught 20 executing
    # against 144 eligible-but-unstarted. This matrix takes 2 of the ~27 slots each queue entry asks
    # for, 10 per wave at a build limit of 5, while the REQUIRED legs wait a median of 41 minutes for
    # a runner. On a slot-bound account a discarded analysis is not free.
    #
    # THE `merge_group:` TRIGGER ABOVE STAYS, deliberately. It is the prerequisite that has to be in
    # place BEFORE these contexts could ever be required, which is the whole point of the comment on
    # it, and removing the trigger is the failure that comment records. This guard skips the WORK,
    # not the trigger.
    #
    # COUPLED CHANGE, recorded in .github/required-contexts.txt beside the reason CodeQL is not
    # required: promoting any CodeQL context to required means REMOVING this guard in the same
    # change, or the context never reports in the queue and nothing merges.
    if: github.repository == 'MEFORORG/MessageFoundry' && github.event_name != 'merge_group'
    runs-on: ubuntu-latest
    # Hang backstop against GitHub's 360-minute default; security.yml's `jobs:` note carries the
    # reasoning and the sizing rule for every cap added in that change. Above the floor because a
    # CodeQL database build is the variable part -- the pair currently runs about 3.3 minutes.
    timeout-minutes: 20
    permissions:
      contents: read
      security-events: write # upload the SARIF results to code scanning
      actions: read
    strategy:
      fail-fast: false
      matrix:
        # python = the engine; javascript-typescript = the ide/ VS Code extension (both ship to the
        # mirror). Both are interpreted — CodeQL needs no build step. Drop a language to narrow scope.
        language: [python, javascript-typescript]
    steps:
      - name: Checkout
        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
        with:
          persist-credentials: false # CodeQL uploads via the job token, not a persisted git credential
      - name: Initialize CodeQL
        uses: github/codeql-action/init@24c54180a607b1449ed407dd24f251e4e9147c8d # v4.38.3
        with:
          languages: ${{ matrix.language }}
          # security-extended adds higher-recall security queries on top of the default suite.
          queries: security-extended
      - name: Analyze
        # THERE IS NO FORK CARVE-OUT ON THIS STEP, AND THAT IS DELIBERATE. The natural assumption is
        # that a fork pull request cannot upload SARIF, because a fork-PR token is read-only and
        # lacks `security-events: write`. The token half is true and the conclusion does not follow:
        # code scanning special-cases the event, and GitHub documents that it "always allows the
        # uploading of results when the `pull_request` event triggers the action run".
        #
        # Measured 2026-09-01 on two genuine fork pull requests to ossf/scorecard -- advanced setup
        # like this file, no repository guard at all, head.repo.fork true. PRs 5159 and 5129 each
        # carry a `CodeQL` check run from app `github-advanced-security` with conclusion success,
        # and that check run exists ONLY because the upload succeeded and was processed.
        #
        # DO NOT ADD A CARVE-OUT. Skipping the upload on forks would delete that `CodeQL` results
        # check, which is the only context that goes red on a real finding: the per-language
        # `CodeQL (<language>)` contexts are the Actions job check runs and fail on build or
        # configuration problems, and github/codeql-action/analyze has no fail-on-findings input.
        # So a carve-out costs the security value outright, and if `CodeQL` were ever required it
        # would also wedge every fork PR forever on a required context that never reports.
        #
        # IF A FUTURE CHANGE ADDS ONE ANYWAY, two traps sit in the obvious spelling of it:
        #
        #   1. `upload: false` does NOT mean "do not upload". getUploadValue in src/actions-util.ts
        #      at the pinned SHA maps both "false" and "failure-only" to "failure-only", a DEBUGGING
        #      mode that still uploads when the run fails. Only "never" suppresses the upload.
        #
        #   2. The fork test MUST lead with the event name. A bare
        #      `github.event.pull_request.head.repo.full_name != github.repository` is TRUE on
        #      merge_group, push, schedule and workflow_dispatch, because there is no pull_request
        #      object and a property read on null yields null. That classifies every non-PR run as a
        #      fork, silently disabling the upload on main itself, so code scanning stops receiving
        #      results while every check stays green. The correct form leads with
        #      `github.event_name == 'pull_request' &&`, which short-circuits before the null read.
        #      Do not "simplify" that conjunct away.
        uses: github/codeql-action/analyze@24c54180a607b1449ed407dd24f251e4e9147c8d # v4.38.3
        with:
          category: "/language:${{ matrix.language }}"