ci: add SonarQube Cloud static analysis and coverage tracking

Apply the org.sonarqube Gradle plugin at the root for multi-module
aggregation, consuming the per-module JaCoCo XML already produced by
pkauth.test-conventions. A dedicated `sonar` CI job runs the build and
submits coverage + analysis, gated to pushes and same-repo PRs (fork
PRs can't read SONAR_TOKEN) with fetch-depth: 0 for SCM blame. The
sonar task is not configuration-cache compatible, so CI invokes it with
--no-configuration-cache (the config cache stays on globally).

Adds ADR 0017 documenting the decision and Quality Gate + Coverage
badges to the README.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: wolpert

.github/workflows/ci.yml

@@ -95,6 +95,36 @@ jobs:
           path: clients/passkeys-browser/reports/mutation/
           if-no-files-found: ignore
 
+  # Run the full build/test, then submit coverage + static analysis to SonarQube Cloud
+  # (free open-source tier). The sonar task is not configuration-cache compatible, so it's
+  # invoked with --no-configuration-cache (gradle.properties enables the config cache globally).
+  sonar:
+    runs-on: ubuntu-latest
+    # SONAR_TOKEN is unavailable to PRs from forks; skip there to avoid a hard failure.
+    if: github.event_name == 'push' || github.event.pull_request.head.repo.full_name == github.repository
+    steps:
+      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6
+        with:
+          # Full history so Sonar can attribute new-code and SCM blame correctly.
+          fetch-depth: 0
+
+      - name: Set up JDK 21
+        uses: actions/setup-java@be666c2fcd27ec809703dec50e508c2fdc7f6654 # v5
+        with:
+          java-version: '21'
+          distribution: 'temurin'
+
+      - name: Validate Gradle wrapper
+        uses: gradle/actions/wrapper-validation@5e2ebd065dc2488b7a6ad670704656cbbe1e8f60 # v6
+
+      - name: Set up Gradle
+        uses: gradle/actions/setup-gradle@5e2ebd065dc2488b7a6ad670704656cbbe1e8f60 # v6
+
+      - name: Build, test, and analyze
+        env:
+          SONAR_TOKEN: ${{ secrets.SONAR_TOKEN }}
+        run: ./gradlew build jacocoTestReport sonar --no-configuration-cache --stacktrace
+
   # Block PRs that introduce dependencies with known vulnerabilities or incompatible
   # licenses, before they merge. Uses the GitHub dependency graph; PR-only.
   dependency-review:

README.md

@@ -2,6 +2,8 @@
 
 ![pk-auth CI](https://github.com/codeheadsystems/pk-auth/actions/workflows/ci.yml/badge.svg)
 [![passkeys-browser mutation score](https://img.shields.io/endpoint?style=flat&label=mutation%20(passkeys-browser)&url=https%3A%2F%2Fbadge-api.stryker-mutator.io%2Fgithub.com%2Fcodeheadsystems%2Fpk-auth%2Fmain%3Fmodule%3Dpasskeys-browser)](https://dashboard.stryker-mutator.io/reports/github.com/codeheadsystems/pk-auth/main?module=passkeys-browser)
+[![Quality Gate Status](https://sonarcloud.io/api/project_badges/measure?project=codeheadsystems_pk-auth&metric=alert_status)](https://sonarcloud.io/summary/new_code?id=codeheadsystems_pk-auth)
+[![Coverage](https://sonarcloud.io/api/project_badges/measure?project=codeheadsystems_pk-auth&metric=coverage)](https://sonarcloud.io/summary/new_code?id=codeheadsystems_pk-auth)
 
 A production-grade, **passkeys-first** authentication template for the JVM.
 pk-auth ships as a reusable library set that can be dropped into a Spring

build.gradle.kts

@@ -3,6 +3,21 @@
 // assemble).
 plugins {
     base
+    alias(libs.plugins.sonarqube)
+}
+
+// SonarQube Cloud analysis. Applied at the root for multi-module aggregation; the scanner
+// auto-detects each module's JaCoCo XML report (build/reports/jacoco/test/jacocoTestReport.xml),
+// produced by pkauth.test-conventions. Run via `./gradlew build jacocoTestReport sonar`.
+// NOTE: the sonar task is not configuration-cache compatible, so CI invokes it with
+// `--no-configuration-cache` (gradle.properties enables the config cache globally).
+sonar {
+    properties {
+        property("sonar.projectKey", "codeheadsystems_pk-auth")
+        property("sonar.organization", "codeheadsystems")
+        property("sonar.host.url", "https://sonarcloud.io")
+        property("sonar.exclusions", "examples/**,clients/passkeys-browser/dist/**")
+    }
 }
 
 // Required for the nmcp aggregation plugin (auto-applied by `nmcp.settings` in settings.gradle.kts)

docs/adr/0017-sonarqube-cloud-static-analysis.md

@@ -0,0 +1,46 @@
+# 17. SonarQube Cloud for static analysis and coverage tracking
+
+Date: 2026-06-11
+
+## Status
+
+Accepted.
+
+## Context
+
+pk-auth already gates quality at build time: Spotless (formatting + SPDX), Error Prone with strict JSpecify null discipline, per-module JaCoCo coverage floors (≥80% on `pk-auth-core`, ≥70% on adapters), and Stryker mutation testing on the browser SDK. What's missing is a *trend* view of the JVM code — coverage over time, code smells, security hotspots, and duplication tracked across commits rather than only pass/fail at HEAD.
+
+We want a hosted dashboard that:
+
+- ingests the JaCoCo XML we already produce, so no new coverage machinery is needed;
+- understands the multi-module Gradle build as one project;
+- is free for a public/open-source repository;
+- runs from CI rather than requiring a separate scan service that can't see our build.
+
+Options considered:
+
+- **SonarQube Cloud (formerly SonarCloud)** — hosted, free for public repos, first-class Gradle scanner (`org.sonarqube`), auto-detects JaCoCo XML, integrates with GitHub PR decoration. No infrastructure to run.
+- **Self-hosted SonarQube Community Edition** — same analyzer, but we'd host and maintain a server + database. Overkill for an open-source library; nobody owns the ops.
+- **Codecov / Coveralls** — coverage trend only; no static analysis, hotspots, or duplication. Narrower than what we want.
+
+## Decision
+
+Adopt **SonarQube Cloud** via the `org.sonarqube` Gradle plugin, driven from CI.
+
+- The plugin (version pinned in `gradle/libs.versions.toml`) is applied to the **root** project only; multi-module aggregation is built in. The `sonar` block in the root `build.gradle.kts` carries `projectKey`, `organization`, host URL, and `sonar.exclusions` (the example apps and the generated browser SDK `dist/`).
+- Coverage is **not** reconfigured — the scanner auto-detects each module's `build/reports/jacoco/test/jacocoTestReport.xml`, already emitted by `pkauth.test-conventions`. The CI step runs `./gradlew build jacocoTestReport sonar`.
+- Analysis runs as a dedicated `sonar` job in `ci.yml`, gated to pushes and same-repo PRs (fork PRs can't read `SONAR_TOKEN`), with `fetch-depth: 0` so Sonar gets full SCM blame for new-code attribution.
+- We use **CI-based analysis**, with Automatic Analysis turned off on the Sonar side — Automatic can't run our Gradle build or see JaCoCo coverage.
+
+## Consequences
+
+- **Positive — trend visibility.** Coverage, code smells, security hotspots, and duplication are tracked per commit with a quality gate on *new code*, complementing (not replacing) the existing per-module JaCoCo floors.
+- **Positive — no new coverage plumbing.** Sonar consumes the JaCoCo XML we already generate.
+- **Negative — config cache caveat.** The `sonar` task is not Gradle configuration-cache compatible, and `gradle.properties` enables the config cache globally. CI invokes the analysis with `--no-configuration-cache`; this is a documented, scoped exception, not a global change.
+- **Negative — fork PRs get no analysis.** GitHub withholds secrets from fork PRs, so the `sonar` job is skipped there. External contributors' branches are covered once merged to `main`; the standard trade-off for an open-source repo.
+- **Negative — heavier CI job.** The `sonar` job runs the full `build` (including the Docker-backed Testcontainers integration tests) so coverage exists when the scanner reads it. Acceptable on `ubuntu-latest`; can be optimized later by sharing coverage artifacts with the existing `build` job.
+
+## Open follow-ups
+
+- If we want the quality gate to block merges, wire the Sonar status check into branch protection.
+- If CI time becomes a concern, have the `sonar` job download JaCoCo artifacts from the `build` job instead of rebuilding.

gradle/libs.versions.toml

@@ -18,6 +18,10 @@ errorprone-plugin = "5.1.0"
 errorprone-core = "2.50.0"
 google-java-format = "1.25.2"
 jspecify = "1.0.0"
+# SonarScanner for Gradle — drives CI-based analysis on SonarQube Cloud (free open-source tier).
+# Applied to the root project for multi-module aggregation; consumes the per-module JaCoCo XML
+# reports already produced by pkauth.test-conventions.
+sonarqube = "7.3.1.8318"
 
 # Runtime — pk-auth-core
 webauthn4j = "0.31.7.RELEASE"
@@ -176,3 +180,4 @@ jackson = ["jackson-databind", "jackson-annotations"]
 [plugins]
 spotless = { id = "com.diffplug.spotless", version.ref = "spotless" }
 errorprone = { id = "net.ltgt.errorprone", version.ref = "errorprone-plugin" }
+sonarqube = { id = "org.sonarqube", version.ref = "sonarqube" }