codeql.yml

# Static analysis of the runner's own source.
#
# Until this landed the only thing standing between a defect in the runner and
# the default branch was a reader. The gate this board is measured against runs
# static analysis on every pull request and surfaces what it finds in the
# code-scanning tab, and this is that half.
#
# Go only. That is what the runner is written in, and record 0001 is where that
# was decided. The workflow files are the other executable thing in this tree and
# they are analysed by zizmor.yml rather than here, so the two tools do not both
# claim the same subject and leave a reader guessing which verdict is which.
#
# The schedule is not decoration. A query published after the last pull request
# reaches this repository on the next scheduled run rather than waiting for
# somebody to open one, and on a board where weeks can pass between changes that
# is the difference between a finding arriving and a finding not arriving.
#
# The job name is what a required set refers to later, and a job renamed in
# passing removes itself from that set while the tab still looks green.
#
# Hardened the way every other workflow in this tree is, because the audit job in
# zizmor.yml refuses a new one that departs from it: permissions denied at the
# top and granted per job, every action pinned to a commit with its version in a
# comment, and checkout without persisted credentials. The one write scope here
# is security-events, which is what uploading the results needs and nothing more.
#
# The version in that comment is the exact one the pinned commit is tagged as,
# never the major. Both spellings leave the same commit running, so the whole
# difference is in what the comment claims. A comment reading v4 is a claim about
# a reference upstream moves, and it stops being true on the day upstream tags a
# release without anybody here touching a file; an exact version is a claim about
# the commit written next to it, which cannot go stale on its own. The two steps
# below carried a major until this comment landed, and were the only two sites in
# this tree that did. The command that says so prints nothing now, and printing
# nothing is the state to keep it in:
#
#   git grep -nE 'uses: .*@[0-9a-f]{40} # v[0-9]+$' -- .github/workflows/
#
# The audit in zizmor.yml reads the comment against the tags the pinned commit
# carries and fails the build on a mismatch, so the spelling is held by a check
# rather than by memory.
name: CodeQL

on:
  pull_request:
    branches: ["**"]
  push:
    branches: [main]
  schedule:
    # Weekly, at a minute nobody else picked, so a newly published query reaches
    # this repository without waiting for a pull request.
    - cron: "41 5 * * 2"

# Explicit deny-all at workflow level; the job below grants only what it needs.
permissions: {}

# Cancel a superseded run on the same ref. This is an analysis job, not a
# publish, so dropping a run that has been overtaken is safe.
concurrency:
  group: ${{ github.workflow }}-${{ github.ref }}
  cancel-in-progress: true

jobs:
  analyse:
    name: CodeQL (go)
    runs-on: ubuntu-latest
    timeout-minutes: 20
    permissions:
      security-events: write # upload the results into the code-scanning tab
      contents: read # checkout the source to analyse
    steps:
      - name: Checkout Repository
        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
        with:
          persist-credentials: false

      - name: Set up Go
        uses: actions/setup-go@b7ad1dad31e06c5925ef5d2fc7ad053ef454303e # v7.0.0
        with:
          # The toolchain comes from go.mod, so the analysis builds with the
          # same compiler the suite does rather than with whatever the image
          # happens to carry.
          go-version-file: go.mod
          cache: false

      - name: Initialise CodeQL
        uses: github/codeql-action/init@ff2f1c621b7f889edc0d3c761ac2e6a3f8cdb0dd # v4.37.7
        with:
          languages: go
          # Manual rather than autobuild, because autobuild builds the module
          # and the module holds the experiments as well. The subject of this
          # workflow is the runner's own source, which is the first line of this
          # file, and under autobuild that sentence was not true of what ran.
          # Record 0017 is where the pattern below is fixed.
          build-mode: manual

      - name: Build the runner
        # The same two roots the build workflow, the suite and the guide name.
        # A finding is reported against what this step compiled, so widening it
        # would put an abandoned prototype in the code-scanning tab under the
        # runner's name.
        run: go build ./cmd/... ./internal/...

      - name: Analyse
        uses: github/codeql-action/analyze@ff2f1c621b7f889edc0d3c761ac2e6a3f8cdb0dd # v4.37.7
        with:
          category: "/language:go"