W2-1 · Release pipeline: JuliaRegistrator + TagBot + SBOM (#43)

## What this does

Implements the wave-2 release pipeline (work order
`.claude/tasks/prod-readiness/w2-1-release-pipeline.md`): release via
**JuliaRegistrator + TagBot** to the Julia General registry, with a
source tarball, an SPDX SBOM, and **real** SLSA provenance attached to
each GitHub Release. The pipeline stays inert until a maintainer
registers a version — no tag is created by this PR.

### Files

- **`.github/workflows/TagBot.yml`** (new) —
`JuliaRegistries/TagBot@e4c81aa…` (SHA-pinned `# v1.25.9`), triggered by
`issue_comment` from `JuliaTagBot` or `workflow_dispatch`; default
`GITHUB_TOKEN` flow (no SSH deploy key, since there is no Documenter
site). Job-level `if` uses only `github.*` context (no
`hashFiles()`/`secrets`), per the repo rule.
- **`.github/workflows/release.yml`** (rewritten) — on `v*` tag push /
`workflow_dispatch(tag)`: build a `git archive` source tarball, generate
an SPDX SBOM with `anchore/sbom-action` (syft, SHA-pinned), compute
**real** `base64-subjects` (`sha256sum … | base64 -w0`) and feed them to
`slsa-framework/slsa-github-generator` (no more `base64-subjects: ""`,
which used to error on every tag), and attach tarball + SBOM +
provenance to the release. All template `TODO` residue removed.
- **`docs/RELEASING.adoc`** (new) — end-to-end maintainer runbook:
version bump → merge → `@JuliaRegistrator register` → registry AutoMerge
→ TagBot → attach-artifacts, with AutoMerge/first-registration caveats
and a first-release checklist.

## Changes in this revision (addressing review must-fix)

1. **BLOCKER — changelog job could never run (so no release was ever
produced).** The `Install git-cliff` step fetched
`releases/latest/download/git-cliff-$(uname
-m)-unknown-linux-gnu.tar.gz`, but git-cliff assets are
**version-stamped** — the current latest asset is
`git-cliff-2.13.1-x86_64-unknown-linux-gnu.tar.gz`, and the versionless
path returns **HTTP 404** (verified below). Under the default `bash -eo
pipefail` shell that failed the step → failed the `changelog` job → and
because `release: needs: [build, changelog]` the release job was
**skipped**, so nothing ever attached. Fixed by pinning
`GIT_CLIFF_VERSION=2.13.1`, building the real versioned asset URL, and
adding `git-cliff --version` to fail fast if the binary is bad
(`release.yml` lines ~121-137).
2. **MISLEADING PIN — `softprops/action-gh-release`.** The SHA
`718ea10b132b3b2eba29c1007bb80653f286566b` was commented `# v2`, but
that SHA is actually tag **v3.0.1 / v3** (the real `v2` points at
`3bb12739…`). Corrected the comment to `# v3.0.1` (`release.yml` line
~177). Confirmed v3.0.1 behaviour is intended, not an accident: at that
SHA the runner is `node24` and every input the workflow uses
(`tag_name`, `files`, `body`, `draft`, `prerelease`,
`generate_release_notes`) exists.
3. **PR now opened** with the SLSA dry-run output and the first-release
checklist below (the two acceptance criteria that require PR-body
content).

## Verification

**`actionlint` 1.7.7 — clean** on both workflows (WSL Debian):

```
$ actionlint .github/workflows/release.yml .github/workflows/TagBot.yml
EXIT=0
```

**git-cliff URL facts (verified via GitHub API + curl):**

```
$ gh api repos/orhun/git-cliff/releases/latest --jq .tag_name
v2.13.1        # asset: git-cliff-2.13.1-x86_64-unknown-linux-gnu.tar.gz
$ curl -sSL -o /dev/null -w "%{http_code}\n" \
    https://github.com/orhun/git-cliff/releases/latest/download/git-cliff-x86_64-unknown-linux-gnu.tar.gz
404
$ curl -sSfL https://github.com/orhun/git-cliff/releases/download/v2.13.1/git-cliff-2.13.1-x86_64-unknown-linux-gnu.tar.gz | tar -tz | grep '/git-cliff$'
git-cliff-2.13.1/git-cliff        # versioned URL downloads; --strip-components=1 lands the binary
```

**softprops SHA fact (verified via GitHub API):** tags at `718ea10b…` =
`v3.0.1`, `v3`; real `v2` = `3bb12739…`; `action.yml@718ea10b…` has
`using: "node24"`.

**SLSA `base64-subjects` dry-run** — ran the exact `release.yml` snippet
on two scratch files (`statistikles-0.1.0.tar.gz`,
`statistikles-0.1.0.spdx.json`) and round-tripped it back:

```
$ sha256sum statistikles-0.1.0.tar.gz statistikles-0.1.0.spdx.json > checksums.txt
$ cat checksums.txt
8f51e5a4968e4a01e5dd77b720ecf8e3a4d2bd5eb01e9a8357b0b6f787a674f3 *statistikles-0.1.0.tar.gz
033f748d28edb19db9e73d8b31ea18fe6f08d668ee43c202e1c20fe5ffc2e28f *statistikles-0.1.0.spdx.json

$ HASHES=$(base64 -w0 checksums.txt)   # this is the base64-subjects value handed to the generator
$ echo "$HASHES"
OGY1MWU1YTQ5NjhlNGEwMWU1ZGQ3N2I3MjBlY2Y4ZTNhNGQyYmQ1ZWIwMWU5YTgzNTdiMGI2Zjc4N2E2NzRmMyAqc3RhdGlzdGlrbGVzLTAuMS4wLnRhci5negowMzNmNzQ4ZDI4ZWRiMTlkYjllNzNkOGIzMWVhMThmZTZmMDhkNjY4ZWU0M2MyMDJlMWMyMGZlNWZmYzJlMjhmICpzdGF0aXN0aWtsZXMtMC4xLjAuc3BkeC5qc29uCg==

$ base64 -d <<<"$HASHES" | sha256sum -c -
statistikles-0.1.0.tar.gz: OK
statistikles-0.1.0.spdx.json: OK
```

The decoded value is exactly the `sha256sum` manifest the generator
expects, and it verifies OK against the files.

## First release checklist

(Also lives in `docs/RELEASING.adoc` for the maintainer.)

- [ ] `version` bumped in `Project.toml` (semver; `0.x` breaking-change
rule — pre-1.0, breaking → minor, non-breaking → patch).
- [ ] `[compat]` complete for every non-stdlib dependency **and**
`julia`, each with an upper bound (`Statistics = "1"` was added in wave
1).
- [ ] PR merged to `main` with **"E2E — Julia Test Suite"** green (Base
ruleset blocks a red merge).
- [ ] Registrator GitHub App installed on the repo (one-time).
- [ ] `@JuliaRegistrator register` commented on the **merge commit on
`main`**.
- [ ] Registry PR AutoMerged — **watch for**: the first-ever
registration sits in a **3-day new-package waiting period**; a missing
`[compat]` upper bound is the usual AutoMerge decline (its PR comment
names the exact guideline; fix in-repo and re-comment).
- [ ] TagBot created the `vX.Y.Z` tag + GitHub Release.
- [ ] **Release** workflow run (*Actions → Release → tag = `vX.Y.Z`*) so
the tarball, SBOM, and SLSA provenance attach. This manual step is
required by default because a `GITHUB_TOKEN`-created tag does not fire
the downstream `push` event; the optional deploy-key upgrade in
`docs/RELEASING.adoc` automates it.

## Skipped / not verified by execution

- Not run: `slsa-github-generator`, `anchore/sbom-action`, TagBot, and
JuliaRegistrator themselves — they only run in GitHub Actions on a real
`v*` tag, and the task forbids creating tags. They are verified by
careful reading + SHA-pinning; the SLSA subject computation (the one
novel shell bit) is dry-run-verified above.
- Out of scope per the work order: actually registering the package,
creating any tag, and container image releases.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

---------

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

Author: hyperpolymath

.github/workflows/TagBot.yml

@@ -0,0 +1,53 @@
+# SPDX-License-Identifier: MPL-2.0
+# Copyright (c) 2026 Jonathan D.A. Jewell (hyperpolymath) <j.d.a.jewell@open.ac.uk>
+#
+# TagBot — cuts the GitHub release + git tag once a new version of Statistikles
+# is merged into the Julia General registry.
+#
+# Flow (see docs/RELEASING.adoc for the full maintainer walkthrough):
+#   1. Maintainer bumps `version` in Project.toml and merges to main.
+#   2. Maintainer comments `@JuliaRegistrator register` on the merge commit.
+#   3. The General registry PR AutoMerges.
+#   4. JuliaTagBot posts a trigger comment here -> this workflow runs -> TagBot
+#      creates the `vX.Y.Z` tag and the GitHub Release.
+#
+# Token model: default GITHUB_TOKEN flow. This package ships no Documenter site,
+# so no SSH deploy key (DOCUMENTER_KEY) is required to push docs; the built-in
+# token can create the release tag. The `ssh` input is therefore omitted (its
+# value is a private-key string, not a boolean, so "off" == not set). One
+# consequence — a tag created via GITHUB_TOKEN does NOT re-trigger other
+# workflows — is documented, with its remedy, in docs/RELEASING.adoc.
+name: TagBot
+
+on:
+  issue_comment:
+    types:
+      - created
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  TagBot:
+    # React only to JuliaTagBot's registry trigger comment or a manual dispatch,
+    # never to arbitrary issue comments. This job-level conditional uses only the
+    # github.* context (no hashFiles()/secrets), per the repo's step-level rule.
+    if: github.event_name == 'workflow_dispatch' || github.actor == 'JuliaTagBot'
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    permissions:
+      actions: read
+      checks: read
+      contents: write
+      deployments: read
+      discussions: read
+      issues: read
+      packages: read
+      pull-requests: read
+      statuses: read
+    steps:
+      - name: Cut GitHub release from the registered version
+        uses: JuliaRegistries/TagBot@e4c81aa138ef4179bddea165bb4a9680c223aca4 # v1.25.9
+        with:
+          token: ${{ secrets.GITHUB_TOKEN }}

.github/workflows/release.yml

@@ -1,44 +1,101 @@
 # SPDX-License-Identifier: MPL-2.0
 # Copyright (c) 2026 Jonathan D.A. Jewell (hyperpolymath) <j.d.a.jewell@open.ac.uk>
 #
-# Release workflow — triggered by version tags (v*).
-# Builds artifacts, generates changelog via git-cliff, creates a GitHub Release,
-# and produces SLSA provenance attestations.
+# Release workflow — attaches distributable artifacts to a Statistikles release.
+#
+# Statistikles is released through the Julia General registry via
+# JuliaRegistrator + TagBot (see docs/RELEASING.adoc). TagBot creates the
+# `vX.Y.Z` git tag and the GitHub Release; this workflow then builds a
+# reproducible source tarball, an SPDX SBOM (syft), and SLSA provenance over
+# both, and attaches them to that release.
+#
+# Trigger model
+# -------------
+# TagBot cuts the tag with the default GITHUB_TOKEN, and GitHub deliberately
+# suppresses the downstream `push:` event (recursive-workflow prevention). So
+# the normal maintainer path is to run this workflow manually via
+# `workflow_dispatch`, passing the `vX.Y.Z` tag TagBot created. The `push: tags`
+# trigger is kept for the optional deploy-key setup described in
+# docs/RELEASING.adoc, under which TagBot's tag push fires this workflow
+# automatically. Either way the pipeline stays inert until a real version is
+# registered — nothing here runs on its own.
 name: Release
 
 on:
   push:
     tags:
       - 'v*'
+  workflow_dispatch:
+    inputs:
+      tag:
+        description: 'Existing git tag to build the release for (e.g. v0.1.0)'
+        required: true
+        type: string
 
 permissions:
   contents: read
 
 jobs:
   build:
-    name: Build Artifacts
+    name: Build Source Tarball + SBOM
     runs-on: ubuntu-latest
     timeout-minutes: 10
     permissions:
       contents: read
+    outputs:
+      version: ${{ steps.meta.outputs.version }}
+      # Real SLSA subjects: sha256sum of the tarball + SBOM, base64-encoded.
+      hashes: ${{ steps.hash.outputs.hashes }}
     steps:
       - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+        with:
+          # Empty on a tag push (checkout uses the pushed tag); the chosen tag on
+          # a manual dispatch.
+          ref: ${{ inputs.tag }}
+
+      - name: Derive version from tag
+        id: meta
+        run: |
+          TAG="${{ inputs.tag || github.ref_name }}"
+          echo "tag=${TAG}" >> "$GITHUB_OUTPUT"
+          echo "version=${TAG#v}" >> "$GITHUB_OUTPUT"
+
+      - name: Generate SPDX SBOM (syft)
+        uses: anchore/sbom-action@e22c389904149dbc22b58101806040fa8d37a610 # v0.24.0
+        with:
+          path: .
+          format: spdx-json
+          output-file: statistikles-${{ steps.meta.outputs.version }}.spdx.json
+          # This workflow uploads the SBOM itself (below) and attaches it to the
+          # release, so the action's own artifact upload is unnecessary.
+          upload-artifact: false
+
+      - name: Build source tarball
+        run: |
+          git archive --format=tar.gz \
+            --prefix="statistikles-${{ steps.meta.outputs.version }}/" \
+            -o "statistikles-${{ steps.meta.outputs.version }}.tar.gz" \
+            HEAD
 
-      - name: Build
+      - name: Compute SLSA base64-subjects
+        id: hash
         run: |
-          echo "Build your artifacts here"
-          # TODO: Replace with your build commands
-          # Examples:
-          #   cargo build --release
-          #   zig build -Doptimize=ReleaseFast
-          #   gleam build
-          #   mix release
-
-      # TODO: Upload build artifacts if needed
-      # - uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
-      #   with:
-      #     name: release-artifacts
-      #     path: target/release/
+          # slsa-github-generator expects `sha256sum` output, base64 (-w0) encoded.
+          sha256sum \
+            "statistikles-${{ steps.meta.outputs.version }}.tar.gz" \
+            "statistikles-${{ steps.meta.outputs.version }}.spdx.json" \
+            > checksums.txt
+          echo "hashes=$(base64 -w0 checksums.txt)" >> "$GITHUB_OUTPUT"
+
+      - name: Upload artifacts for the release job
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
+        with:
+          name: release-artifacts
+          path: |
+            statistikles-*.tar.gz
+            statistikles-*.spdx.json
+          if-no-files-found: error
+          retention-days: 5
 
   changelog:
     name: Generate Changelog
@@ -52,16 +109,32 @@ jobs:
     steps:
       - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
         with:
+          ref: ${{ inputs.tag }}
           fetch-depth: 0
 
       - name: Extract version from tag
         id: version
-        run: echo "version=${GITHUB_REF_NAME#v}" >> "$GITHUB_OUTPUT"
+        run: |
+          TAG="${{ inputs.tag || github.ref_name }}"
+          echo "version=${TAG#v}" >> "$GITHUB_OUTPUT"
 
       - name: Install git-cliff
+        env:
+          # git-cliff release assets are version-stamped (e.g.
+          # git-cliff-2.13.1-x86_64-unknown-linux-gnu.tar.gz), so the versionless
+          # `releases/latest/download/...` path returns HTTP 404 and, under the
+          # default `bash -eo pipefail` shell, fails this step -> fails the
+          # changelog job -> skips `release` (needs: [build, changelog]). Pin an
+          # explicit version and build the real, versioned asset URL. Bump this
+          # value to adopt a newer git-cliff.
+          GIT_CLIFF_VERSION: '2.13.1'
         run: |
-          curl -sSfL https://github.com/orhun/git-cliff/releases/latest/download/git-cliff-$(uname -m)-unknown-linux-gnu.tar.gz \
-            | tar -xz --strip-components=1 -C /usr/local/bin/ git-cliff-*/git-cliff
+          ARCH="$(uname -m)"
+          curl -sSfL \
+            "https://github.com/orhun/git-cliff/releases/download/v${GIT_CLIFF_VERSION}/git-cliff-${GIT_CLIFF_VERSION}-${ARCH}-unknown-linux-gnu.tar.gz" \
+            | tar -xz --strip-components=1 -C /usr/local/bin/ "git-cliff-${GIT_CLIFF_VERSION}/git-cliff"
+          # Fail fast (and visibly) if the binary did not land or cannot run.
+          git-cliff --version
 
       - name: Generate changelog for this release
         id: cliff
@@ -87,46 +160,46 @@ jobs:
           retention-days: 5
 
   release:
-    name: Create GitHub Release
+    name: Attach Artifacts to GitHub Release
     needs: [build, changelog]
     runs-on: ubuntu-latest
     timeout-minutes: 10
     permissions:
       contents: write
     steps:
-      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
-
-      # TODO: Download build artifacts if uploading to the release
-      # - uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093 # v4
-      #   with:
-      #     name: release-artifacts
-      #     path: artifacts/
+      - name: Download build artifacts
+        uses: actions/download-artifact@37930b1c2abaa49bbe596cd826c3c89aef350131 # v7.0.0
+        with:
+          name: release-artifacts
+          path: artifacts
 
-      - name: Create GitHub Release
-        uses: softprops/action-gh-release@718ea10b132b3b2eba29c1007bb80653f286566b # v2
+      - name: Create or update GitHub Release
+        uses: softprops/action-gh-release@718ea10b132b3b2eba29c1007bb80653f286566b # v3.0.1
         with:
+          tag_name: ${{ inputs.tag || github.ref_name }}
           body: ${{ needs.changelog.outputs.changelog }}
           draft: false
-          prerelease: ${{ contains(github.ref_name, '-rc') || contains(github.ref_name, '-beta') || contains(github.ref_name, '-alpha') }}
+          prerelease: ${{ contains(inputs.tag || github.ref_name, '-rc') || contains(inputs.tag || github.ref_name, '-beta') || contains(inputs.tag || github.ref_name, '-alpha') }}
           generate_release_notes: false
-          # TODO: Add artifact files to the release
-          # files: |
-          #   artifacts/*
+          files: |
+            artifacts/*
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
 
   provenance:
     name: SLSA Provenance
-    needs: [build]
+    needs: [build, release]
     permissions:
       actions: read
       id-token: write
       contents: write
-    # SLSA generator must run in a separate, isolated workflow
+    # SLSA generator must run in a separate, isolated (reusable) workflow.
     # See: https://slsa.dev/spec/v1.0/requirements#build-l3
+    # Subjects are the real sha256sums computed by the build job (no longer "").
     uses: slsa-framework/slsa-github-generator/.github/workflows/generator_generic_slsa3.yml@f7dd8c54c2067bafc12ca7a55595d5ee9b75204a # v2.1.0
     with:
-      base64-subjects: ""
-      # TODO: Replace with actual artifact hashes
-      # Generate with: sha256sum artifact | base64 -w0
-      # base64-subjects: "${{ needs.build.outputs.hashes }}"
+      base64-subjects: ${{ needs.build.outputs.hashes }}
+      upload-assets: true
+      # Empty on a tag push (generator uses the pushed tag); the chosen tag on a
+      # manual dispatch, as the generic generator requires off-tag runs.
+      upload-tag-name: ${{ inputs.tag }}