codeql.yml

name: CodeQL

on:
  push:
    branches: [main, development, nightly, 'feature/**']
  pull_request:
    branches: [main, development, nightly]
  schedule:
    - cron: '30 3 * * 1' # Mondays ~03:30 UTC, off the top of the hour
  workflow_dispatch:

concurrency:
  # PRs: cancel the scan for superseded commits on the same PR (the old
  # code no longer matters). Pushes: key on the commit SHA, not the branch
  # name — otherwise a second push to the same branch before CodeQL
  # finishes cancels the first commit's scan and leaves it with a
  # permanently cancelled/red check instead of a result.
  group: ${{ github.workflow }}-${{ github.event_name == 'pull_request' && github.head_ref || github.sha }}
  cancel-in-progress: true

permissions:
  contents: read
  security-events: write

jobs:
  analyze:
    name: CodeQL analysis (${{ matrix.language }})
    runs-on: ubuntu-latest
    permissions:
      contents: read
      security-events: write
    strategy:
      fail-fast: false
      matrix:
        # This is a pure Go library — no JS/TS source exists to scan.
        language: [go]
    steps:
      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
        with:
          persist-credentials: false

      # KNOWN GAP: as of CodeQL CLI 2.26.3, the bundled Go extractor is
      # built with go1.26.5. go.mod declares `go 1.27.0`, so every source
      # file fails extraction ("package requires newer Go version go1.27
      # (application built with go1.26)") and the scan silently produces
      # zero results — the job still goes green because "0 findings" and
      # "CodeQL scanned nothing" look identical from the gate's output.
      # This is a temporary upstream lag (CodeQL's Go extractor toolchain
      # trailing the latest Go release), not a config bug here. Once
      # GitHub ships a CodeQL bundle whose Go extractor supports 1.27,
      # this comment (and the two below) can be deleted.
      - uses: actions/setup-go@b7ad1dad31e06c5925ef5d2fc7ad053ef454303e # v7
        with:
          go-version-file: go.mod
          cache-dependency-path: go.sum

      - uses: github/codeql-action/init@6f2ac81f5cd81fe351a197ba0b00d91d03cd2aee # v4.39.0
        with:
          languages: ${{ matrix.language }}
          queries: security-and-quality

      - uses: github/codeql-action/autobuild@6f2ac81f5cd81fe351a197ba0b00d91d03cd2aee # v4.39.0

      - id: codeql_analyze
        uses: github/codeql-action/analyze@6f2ac81f5cd81fe351a197ba0b00d91d03cd2aee # v4.39.0
        with:
          category: "/language:${{ matrix.language }}"
          output: sarif-results/${{ matrix.language }}

      # Report-only — see the blocking step below. Every CodeQL result
      # blocks by default unless suppressed (in-source `codeql[rule-id]`
      # comment, or a matching non-expired entry in
      # .github/codeql/codeql-suppressions.yml); this step never fails the
      # job itself, it just surfaces the gate's verdict in the job summary.
      - name: Report CodeQL findings gate
        if: always() && steps.codeql_analyze.conclusion != 'skipped'
        run: |
          set -euo pipefail
          SARIF_DIR="sarif-results/${{ matrix.language }}"
          SARIF_FILE="$(find "$SARIF_DIR" -maxdepth 1 -type f -name '*.sarif' | head -n 1 || true)"

          {
            echo "## CodeQL findings gate — ${{ matrix.language }}"
            echo '```'
          } >>"$GITHUB_STEP_SUMMARY"

          if [ -z "$SARIF_FILE" ] || [ ! -r "$SARIF_FILE" ]; then
            echo "ERROR: expected SARIF file missing or unreadable under $SARIF_DIR" | tee -a "$GITHUB_STEP_SUMMARY"
            echo '```' >>"$GITHUB_STEP_SUMMARY"
            exit 0
          fi

          set +e
          bash scripts/security/codeql-findings-gate.sh "$SARIF_FILE" "${{ matrix.language }}" | tee -a "$GITHUB_STEP_SUMMARY"
          set -e

          # "0 findings" is indistinguishable from "extraction failed and
          # nothing was scanned" by output alone, and CodeQL's bundled Go
          # extractor is known to trail the go.mod `go` directive (see the
          # setup-go step above) — an unconditional note beats a clever
          # after-the-fact detector: this job has no reliable way to
          # inspect the autobuild step's own log/annotations from a later
          # step, so a conditional check here would just be a check that
          # can silently never fire.
          {
            echo '```'
            echo "_Before trusting a 0-finding result: check the \`autobuild\` step's log for \`requires newer Go version\` errors — if present, CodeQL scanned nothing and this is not a clean pass._"
            echo "View full results in the [Security tab](https://github.com/${{ github.repository }}/security/code-scanning)"
          } >>"$GITHUB_STEP_SUMMARY"

      - name: Enforce CodeQL findings gate
        if: always() && steps.codeql_analyze.conclusion != 'skipped'
        run: |
          set -euo pipefail
          SARIF_DIR="sarif-results/${{ matrix.language }}"
          SARIF_FILE="$(find "$SARIF_DIR" -maxdepth 1 -type f -name '*.sarif' | head -n 1 || true)"

          if [ -z "$SARIF_FILE" ] || [ ! -r "$SARIF_FILE" ]; then
            echo "::error::Expected SARIF file is missing or unreadable under $SARIF_DIR"
            exit 1
          fi

          if ! bash scripts/security/codeql-findings-gate.sh "$SARIF_FILE" "${{ matrix.language }}" >/dev/null; then
            echo "::error::CodeQL found blocking findings. Fix before merging, or add a documented exception in .github/codeql/codeql-suppressions.yml (see that file's header for the policy)."
            exit 1
          fi