release: bring development into release-0.2.0

.github/pull_request_template.md

@@ -0,0 +1,11 @@
+## Description
+
+<!-- What does this change do, and why? -->
+
+Fixes/Refs #<!-- required -->
+
+## Checklist
+
+- [ ] Self-review done
+- [ ] End-to-end verification done
+- [ ] Docs (`CLAUDE.md` / ADRs) updated, if applicable

.github/workflows/ci-release.yml

@@ -84,7 +84,6 @@ jobs:
       - uses: actions/checkout@v4
         with:
           fetch-depth: 0
-      - uses: ./.github/actions/trivy-cache
 
       # First, before the registry logins: this action replaces the Docker
       # credential store wholesale, while `docker login` merges into it, so the
@@ -109,13 +108,13 @@ jobs:
           username: ${{ github.actor }}
           password: ${{ secrets.GHCR_PAT || secrets.GITHUB_TOKEN }}
 
-      # Builds the image into this runner's local Docker daemon and gates it on
-      # Trivy — exit 1 on a finding, not a report — so the exact bytes about to
-      # ship are scanned before they are tagged for or pushed to any registry.
+      # Builds into this runner's local Docker daemon so the next step re-tags
+      # these exact bytes. No Trivy here — ci.yml and security.yml already scan
+      # this image; see image-build in the Makefile.
       - run: make image-build ARCH=${{ matrix.arch }}
 
-      # Re-tags that same scanned image and pushes it. No rebuild and no
-      # re-scan, so what lands in the registry is what the gate above passed.
+      # Re-tags that local image and pushes it. No rebuild, so every registry
+      # gets identical bytes.
       - run: make image-push ARCH=${{ matrix.arch }}
 
   publish-artifact:

.github/workflows/ci.yml

@@ -1,21 +1,27 @@
 name: CI
 
 # Two checks from THIS file and no more: "End to End verification" and
-# "Security Scan". A PR carries two further checks, both from codeql.yml:
-# "CodeQL", which is its job, and "Code scanning results / CodeQL", which
-# GitHub posts for the analysis upload and which is not a job at all — it
-# cannot be renamed, reordered or switched off.
+# "Security Scan" — the latter runs Trivy AND CodeQL as steps in one job, so a
+# PR carries exactly these two controllable checks. CodeQL has no job of its
+# own that triggers on pull_request; security.yml's trunk job runs the same
+# analyze step again on every push and on its weekly schedule, which is what
+# keeps the baseline fresh for the "new alerts in this PR" comparison this
+# job's own CodeQL run reads against.
 #
-# That second one is the exact shape this file refuses for Trivy further
-# down, so the rule has to be stated properly rather than by count. What it
-# refuses is a check that can report the OPPOSITE of a gate reading the same
-# findings. Trivy has such a gate, make trivy-gate, and the upload goes green
-# with "No new alerts in code change" whenever the findings are not new to the
-# diff — while the gate fails on the same SARIF. CodeQL has no gate to
-# contradict: it is the only thing here that reports its class, and codeql.yml
-# deliberately does not fail on findings. So its results check is redundant
-# rather than contradictory. Redundant is a cost worth paying for per-PR
-# alerts; a check that can be green while the truth is red is not.
+# The one entry this cannot remove: GitHub posts "Code scanning results /
+# CodeQL" itself for the SARIF upload inside codeql-action/analyze, which is
+# not a job and so has no `name:` of its own and cannot be renamed, reordered
+# or switched off — see the comment on that step in security-scan. That is
+# the exact shape this file refuses for Trivy further down, so the rule has
+# to be stated properly rather than by count: what it refuses is a check that
+# can report the OPPOSITE of a gate reading the same findings. Trivy has such
+# a gate, make trivy-gate, and the upload goes green with "No new alerts in
+# code change" whenever the findings are not new to the diff — while the gate
+# fails on the same SARIF. CodeQL has no gate to contradict: it is the only
+# thing here that reports its class, and analyze deliberately does not fail
+# on findings. So its results check is redundant rather than contradictory.
+# Redundant is a cost worth paying for per-PR alerts; a check that can be
+# green while the truth is red is not.
 #
 # The two tag-time checks live in ci-release.yml, not here behind an `if:`. A
 # job whose `if:` is false still posts a *skipped* check, and its `name:` is
@@ -140,19 +146,71 @@ jobs:
   security-scan:
     name: Security Scan
     runs-on: ubuntu-latest
-    # Both scans in one job, one check. They were two jobs plus a gate job, and
-    # three red-or-green checks to answer one question — "is this branch
-    # shippable" — was more to read than it was worth. The dependency scan
-    # needs only a checkout, so it runs first and its findings are in the log
-    # before the image has finished building.
+    # CodeQL and both Trivy scans, one job, one check — a PR gets exactly two
+    # checks total from this repo's controllable CI (this job and verify
+    # above). security.yml's trunk job runs CodeQL again on a trunk push and
+    # on its weekly schedule for the "new alerts in this PR" baseline and the
+    # deep re-scan a push trigger can never give, but CodeQL has no job of its
+    # own that triggers on pull_request — this job is the only place a PR
+    # sees CodeQL run.
     #
-    # pull-requests: write is the PR comment. No security-events: write — the
-    # SARIF upload is gone, see below.
+    # The one thing folding it in here does NOT remove: GitHub posts its own
+    # "Code scanning results / CodeQL" check for the SARIF upload inside
+    # codeql-action/analyze below, regardless of which job hosts that step.
+    # It is not a workflow job, has no `name:` of its own and cannot be
+    # suppressed — see the comment on that step for why it is accepted rather
+    # than refused the way a Trivy SARIF upload is refused further down.
+    #
+    # pull-requests: write is the PR comment. security-events: write is
+    # CodeQL's own SARIF upload — Trivy's SARIF upload is NOT taken here, see
+    # the comment further down for why that one stays PR-forbidden even
+    # though this permission would allow it.
     permissions:
       contents: read
       pull-requests: write
+      security-events: write
     steps:
       - uses: actions/checkout@v4
+      - uses: actions/setup-go@v5
+        with:
+          go-version-file: go.mod
+          cache-dependency-path: "**/go.sum"
+
+      # CodeQL first — it only needs the Go toolchain and `make build`, so it
+      # runs before anything Docker-shaped and does not care whether this PR
+      # is from a fork (no secrets involved).
+      - uses: github/codeql-action/init@v4
+        with:
+          languages: go
+          # manual, not autobuild: autobuild guesses at how to build a Go
+          # module, and this one is built one way — `make build`, over every
+          # package, with the ldflags that stamp buildinfo. A CodeQL database
+          # extracted from a build nobody else performs describes a program
+          # nobody else runs.
+          build-mode: manual
+          # security-extended, not the default suite. The default returned
+          # zero on this tree, which is the only condition under which
+          # widening is cheap: there is no backlog for the extra queries to
+          # be lost in, so anything this surfaces is both new and
+          # attributable. It adds the lower-confidence and harder-to-exploit
+          # queries — the ones worth reading rather than the ones worth
+          # blocking on, which is why this step still does not fail the job
+          # on findings.
+          queries: security-extended
+
+      - run: make build
+
+      # An explicit category so this analysis sits beside trivy-deps and
+      # trivy-image in the Security tab rather than competing with them for
+      # the default one, and so it matches security.yml's trunk runs for the
+      # "new alerts" comparison. Findings do NOT fail this job: analyze files
+      # alerts and exits 0. This upload IS allowed on a PR, unlike Trivy's
+      # below: CodeQL has no competing gate anywhere in this repo, so there is
+      # nothing for its own check to contradict.
+      - uses: github/codeql-action/analyze@v4
+        with:
+          category: codeql-go
+
       - uses: ./.github/actions/trivy-cache
 
       # Fork PRs get an empty string for every secrets.* reference, so the

.github/workflows/security.yml

@@ -1,7 +1,13 @@
 name: Security
 
 # The badge on the README and the alert list behind it: what is wrong with the
-# trunk today, as opposed to what a PR changed.
+# trunk today, as opposed to what a PR changed. One job, one check: Trivy
+# (dependency + image), govulncheck, and CodeQL all run here, the same way
+# ci.yml's security-scan job runs Trivy and CodeQL together for a PR. CodeQL
+# used to be a separate job in its own codeql.yml, triggered by this same push
+# and schedule — folded in here so a push to the trunk (which is also every
+# push PR #36, release-0.0.1 -> main, will ever see) posts one job-check
+# instead of two.
 #
 # The weekly schedule is the point of this file. ci.yml scans every PR, which
 # answers "did this diff introduce a vulnerability" — it structurally cannot
@@ -29,7 +35,10 @@ on:
   schedule:
     # Monday 03:17 UTC. Off the hour on purpose — GitHub queues scheduled runs
     # hardest at :00, and a scan that starts twenty minutes late is a scan
-    # whose result is twenty minutes late.
+    # whose result is twenty minutes late. One entry, not two: this used to sit
+    # an hour apart from codeql.yml's own cron so the two jobs' scheduled runs
+    # never queued against each other: now that CodeQL is a step in this same
+    # job, there is only one run to schedule.
     #
     # A schedule only ever runs on the DEFAULT branch, whatever the push
     # trigger above lists. So until this file is on main, the weekly scan does
@@ -59,14 +68,33 @@ jobs:
       security-events: write
     steps:
       - uses: actions/checkout@v4
-      - uses: ./.github/actions/trivy-cache
-      # govulncheck is built from tools/go.mod, so this job needs a toolchain
-      # even though the Trivy half of it does not.
+      # govulncheck is built from tools/go.mod and CodeQL's build-mode is
+      # manual, so this job needs a toolchain even though the Trivy half of
+      # it does not.
       - uses: actions/setup-go@v5
         with:
           go-version-file: go.mod
           cache-dependency-path: "**/go.sum"
 
+      # CodeQL first, same as ci.yml's security-scan job: it only needs the Go
+      # toolchain and `make build`, so it runs before anything Docker-shaped.
+      - uses: github/codeql-action/init@v4
+        with:
+          languages: go
+          build-mode: manual
+          queries: security-extended
+
+      - run: make build
+
+      # Same category as ci.yml's security-scan job uses on a PR, so a PR's
+      # analysis is compared against the trunk's most recent one under this
+      # exact category — that comparison is what "new alerts in this PR" means.
+      - uses: github/codeql-action/analyze@v4
+        with:
+          category: codeql-go
+
+      - uses: ./.github/actions/trivy-cache
+
       # Both scans, for the reasons ci.yml gives at length: the dependency scan
       # sees a vulnerable module that only the test suite imports and is never
       # linked into a layer, and the image scan sees stdlib CVEs read out of the

Makefile

@@ -336,21 +336,13 @@ trivy-deps: $(TRIVY)
 	$(TRIVY) fs . --skip-dirs tools --severity $(SEVERITY) --exit-code 0 \
 		--format sarif --output trivy-deps.sarif
 
-TRIVY_IMAGE_SCAN = $(TRIVY) image $(IMAGE) --severity $(SEVERITY)
-
 ## trivy-image: shipped image scan (T4), SARIF report — reads base layers and
 ##              the Go build info embedded in the binary, including stdlib,
 ##              so a Go toolchain CVE shows up here and nowhere else that the
 ##              dependency scan above cannot see. IMAGE names the ref to scan.
 trivy-image: $(TRIVY)
-	$(TRIVY_IMAGE_SCAN) --exit-code 0 --format sarif --output trivy-image.sarif
-
-## trivy-release-gate: the same image scan as trivy-image, but exit 1 on a
-##                     finding instead of writing a report — the pre-push
-##                     release gate image-build runs once per arch, on the
-##                     local image, before anything is pushed anywhere.
-trivy-release-gate: $(TRIVY)
-	$(TRIVY_IMAGE_SCAN) --exit-code 1 --format table
+	$(TRIVY) image $(IMAGE) --severity $(SEVERITY) \
+		--exit-code 0 --format sarif --output trivy-image.sarif
 
 ## trivy-report: render every SARIF report as ONE PR comment, trivy-report.md
 # One comment covering both scans, not one comment each: the two scans run in
@@ -533,21 +525,23 @@ docker:
 	  --build-arg TREE_STATE=$(TREE_STATE) \
 	  -t $(IMAGE) .
 
-## image-build: build this arch's release image locally and gate it on Trivy
-# Built and loaded locally, NOT pushed: Trivy then scans the exact bytes that
-# are about to ship, before they are tagged for or pushed to any registry. One
-# scan covers every registry, because it is one image.
+## image-build: build this arch's release image locally (ARCH)
+# Built and loaded locally, NOT pushed, so image-push re-tags these exact bytes.
+#
+# No Trivy here. The same image is scanned on the PR, where trivy-gate blocks
+# the merge, and again by security.yml on the push to the release branch and
+# weekly after that. A fourth scan at tag time reports nothing new and can only
+# stop the release — #46.
 #
 # Native, never QEMU — each arch builds on a runner of that arch, so a plain
 # `docker build` already produces the right one and ARCH is only the tag suffix.
 image-build:
 	$(MAKE) docker IMAGE=$(RELEASE_IMAGE)
-	$(MAKE) trivy-release-gate IMAGE=$(RELEASE_IMAGE)
 
-## image-push: push the gated local image to every enabled registry (ARCH)
-# Re-tags the already-scanned local image per registry and pushes. No rebuild
-# and no re-scan, so what is pushed is byte-identical to what image-build
-# gated. One arch-suffixed tag each; nothing binds the plain version tag until
+## image-push: push this arch's local release image to every registry (ARCH)
+# Re-tags the local image per registry and pushes. No rebuild, so what is pushed
+# is byte-identical across every registry and to what image-build produced. One
+# arch-suffixed tag each; nothing binds the plain version tag until
 # image-publish has every arch.
 image-push: require-image-repos
 	@set -e; for repo in $(IMAGE_REPOS); do \
@@ -743,7 +737,7 @@ $(TRIVY):
 .PHONY: help build test test-short test-ci cover cover-total cover-report \
 	cover-html cover-diff lint fmt lint-actions lint-staged hooks sqlc \
 	sqlc-verify migrate run logs migrate-down security trivy-deps \
-	trivy-image trivy-release-gate trivy-report trivy-gate docker \
+	trivy-image trivy-report trivy-gate docker \
 	image-build image-push image-publish require-image-repos up down \
 	verify newman audit tools clean telemetry telemetry-metrics \
 	telemetry-logs telemetry-down