codeql.yml

name: CodeQL

# CodeQL static analysis for Go. Runs on every PR, every push to main,
# and weekly to catch new query packs landing upstream. Findings appear
# in the Security tab; default-severity ERROR also fails the PR check.
#
# Why this AND Semgrep? Different rule packs catch different classes of
# bugs — Semgrep is great at custom org-policy patterns, CodeQL is better
# at dataflow-heavy queries (taint sinks, SSRF, SQLi-style). They overlap
# but the union finds more.

on:
  push:
    # Direct pushes to main only (post-merge). PR commits are covered
    # by the pull_request event below.
    #
    # Scorecard's SAST check counts merged PRs on the default branch
    # and asks whether a SAST tool ran successfully on each PR's HEAD
    # commit. Every commit landing in main arrives via a merged PR
    # (pull_request scan) or a direct push (push scan), so coverage is
    # complete without the `['**']` net that triggered duplicate runs
    # for every PR commit — push and pull_request fired on the same
    # SHA, one was cancelled by the concurrency group, leaving noisy
    # "cancelled" entries on every PR's checks page.
    branches: [main]
  pull_request:
    branches: [main]
    paths-ignore:
      - '*.md'
      - 'LICENSE'
      - 'CODEOWNERS'
      - '.gitignore'
      - '.agents/**'
      - '.workflow/**'
      - '.github/*.md'
      - '.github/ISSUE_TEMPLATE/**'
  schedule:
    # Sunday 04:23 UTC — off-peak, off-Monday-morning.
    - cron: '23 4 * * 0'
  workflow_dispatch:

# REF-keyed, not SHA-keyed, and the difference is load-bearing on the CI fleet
# (2 usable slots — see govulncheck.yml for the full note and the measured
# 40-minute incident). A SHA-keyed group opens a NEW group on every
# force-push, so the run on the abandoned commit is never cancelled and keeps
# holding its runner. `github.ref` is stable across force-pushes to the same
# PR, so a superseded run is cancelled and its slot released immediately. A
# manual rerun on the same ref also still supersedes the in-flight run, which
# is what the original SHA keying was for.
concurrency:
  group: ${{ github.workflow }}-${{ github.ref }}
  cancel-in-progress: true

permissions:
  contents: read

jobs:
  analyze:
    name: Analyze Go
    runs-on: ubuntu-24.04
    timeout-minutes: 30
    permissions:
      contents: read
      security-events: write  # upload SARIF to the Security tab
      actions: read           # CodeQL templates fetch workflow metadata

    strategy:
      fail-fast: false
      matrix:
        language: [go]

    steps:
      - name: Checkout
        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1  # v7.0.1
        with:
          persist-credentials: false

      # Pin Go to the version declared in go.mod. Without this, CodeQL
      # Autobuild uses the runner's bundled Go (older than our 1.25.x
      # directive), which fails the compile and surfaces as a CI red
      # rather than a real finding (gemini round-1 P2).
      - name: Set up Go
        uses: actions/setup-go@b7ad1dad31e06c5925ef5d2fc7ad053ef454303e  # v7.0.0
        with:
          go-version-file: go.mod
          cache: false

      - name: Initialize CodeQL
        uses: github/codeql-action/init@5595ccaf912efad79be6eef63a5619ff05969be3  # v4.37.6
        with:
          languages: ${{ matrix.language }}
          # security-extended adds queries beyond the default "security
          # and quality" pack — taint tracking, less-common sink types,
          # crypto misuses. Worth the extra ~2 min run-time for an OSS
          # supply-chain tool.
          queries: security-extended

      - name: Autobuild
        uses: github/codeql-action/autobuild@5595ccaf912efad79be6eef63a5619ff05969be3  # v4.37.6

      - name: Perform analysis
        uses: github/codeql-action/analyze@5595ccaf912efad79be6eef63a5619ff05969be3  # v4.37.6
        with:
          category: /language:${{ matrix.language }}