Release #110

Workflow file for this run

.github/workflows/release.yml at 48e5d16

	name: Release

	# Triggered from the Actions "Run workflow" UI. A pushed tag is no
	# longer the trigger: the GitHub Releases UI cannot drive the
	# draft-first immutable publish flow (a draft release never creates a
	# tag, so no push event fires). Publishing jobs (npm, pypi, vscode,
	# release, winget-submit) declare `environment: release` for its
	# secrets and OIDC scope; the single required-reviewer rule lives on
	# the separate `release-approval` environment, used only by the
	# `gate` job that every credential job lists in `needs:`. So one
	# approval releases every channel and no secret is reachable before
	# it. preflight/build/obsidian/flatpak run ahead of the gate. The
	# `release` job creates the tag itself. See
	# docs/development/release.md.
	on:
	workflow_dispatch:
	inputs:
	version:
	description: "Release version, e.g. v0.13.0 (must start with v)"
	required: true
	type: string

	permissions:
	contents: read

	env:
	VERSION: ${{ inputs.version }}

	# Serialize release runs so two publish jobs cannot mint OIDC tokens
	# against the same registry at the same time. `cancel-in-progress:
	# false` keeps the first release going (cancelling mid-publish would
	# leave the scoped platform packages out of sync with the root
	# package).
	concurrency:
	group: release
	cancel-in-progress: false

	jobs:
	# Validate the tag before any credential-bearing job runs. The tag
	# is read through an env var, never interpolated into the shell, so
	# a crafted value cannot inject commands (zizmor template-expansion
	# rule). This job also carries the repository guard anchor reused by
	# every publishing job.
	preflight:
	runs-on: ubuntu-latest
	if: &release_repo_trigger_ok >-
	github.repository == 'jeduden/mdsmith'
	steps:
	- name: Validate version tag
	env:
	INPUT_VERSION: ${{ inputs.version }}
	run: \|
	if ! printf '%s' "$INPUT_VERSION" \| \
	grep -Eq '^v[0-9]+\.[0-9]+\.[0-9]+([-.+][0-9A-Za-z.-]+)?$'; then
	echo "version must look like v1.2.3 (got '$INPUT_VERSION')" >&2
	exit 1
	fi
	echo "release version: $INPUT_VERSION"

	# Generate the PGO profile once, ahead of the build matrix, so every
	# platform binary is built profile-guided. The profile is recorded
	# over the two benchmark corpora in both configurations and merged
	# into cmd/mdsmith/default.pgo — a gitignored path `go build` reads
	# automatically. It is never committed; it travels to the build jobs
	# as the `pgo-profile` artifact. See docs/development/pgo-profile.md.
	pgo:
	needs: [preflight]
	if: *release_repo_trigger_ok
	runs-on: ubuntu-latest
	steps:
	- uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
	with:
	persist-credentials: false
	- uses: actions/setup-go@7a3fe6cf4cb3a834922a1244abfce67bcef6a0c5 # v6.2.0
	with:
	go-version-file: go.mod
	cache: false
	- name: Build mdsmith-release
	run: go build -o mdsmith-release ./cmd/mdsmith-release
	- name: Generate PGO profile
	run: ./mdsmith-release pgo /tmp/mdsmith-pgo
	- uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4.6.2
	with:
	name: pgo-profile
	path: cmd/mdsmith/default.pgo
	if-no-files-found: error

	build:
	needs: [preflight, pgo]
	if: *release_repo_trigger_ok
	strategy:
	matrix:
	include:
	- goos: linux
	goarch: amd64
	- goos: linux
	goarch: arm64
	- goos: darwin
	goarch: amd64
	- goos: darwin
	goarch: arm64
	- goos: windows
	goarch: amd64
	runs-on: ubuntu-latest
	steps:
	- uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
	with:
	persist-credentials: false
	- uses: actions/setup-go@7a3fe6cf4cb3a834922a1244abfce67bcef6a0c5 # v6.2.0
	with:
	go-version-file: go.mod
	cache: false
	# Place the profile the `pgo` job generated so `go build` picks it
	# up from cmd/mdsmith/default.pgo automatically; the build below is
	# otherwise unchanged. The path is gitignored, so nothing is
	# committed.
	- name: Download PGO profile
	uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093 # v4.3.0
	with:
	name: pgo-profile
	path: cmd/mdsmith/
	- name: Confirm the build is profile-guided
	run: \|
	test -s cmd/mdsmith/default.pgo
	echo "building with PGO profile cmd/mdsmith/default.pgo ($(wc -c < cmd/mdsmith/default.pgo) bytes)"
	- name: Build
	env:
	GOOS: ${{ matrix.goos }}
	GOARCH: ${{ matrix.goarch }}
	# Disable cgo so the native linux/amd64 build resolves
	# net and os/user purely in Go. Cross-compiles already
	# auto-disable CGO; the native build would otherwise
	# bind glibc's resolver into the binary, breaking the
	# manylinux_2_17 wheel and the @mdsmith/linux-x64 npm
	# package on Alpine/musl and on systems whose glibc is
	# older than the wheel tag claims. macOS and Windows
	# binaries still link the platform syscall layer
	# (libSystem, kernel32) — this knob is about avoiding
	# glibc on Linux, not achieving full static linkage.
	CGO_ENABLED: "0"
	VERSION: ${{ env.VERSION }}
	run: \|
	ext=""
	if [ "$GOOS" = "windows" ]; then ext=".exe"; fi
	bin="mdsmith-${GOOS}-${GOARCH}${ext}"
	go build -trimpath -ldflags="-s -w -X main.version=${VERSION}" -o "$bin" ./cmd/mdsmith
	echo "bin=$bin" >> "$GITHUB_ENV"
	- uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4.6.2
	with:
	name: mdsmith-${{ matrix.goos }}-${{ matrix.goarch }}
	path: ${{ env.bin }}

	# Single human-approval chokepoint for the entire release. The lone
	# required-reviewer rule now lives on the `release-approval`
	# environment and this job is its only user, so the maintainer
	# approves exactly once. Every credential-bearing job — `npm`,
	# `pypi`, `vscode`, `release`, `winget-submit` — lists `gate` in
	# `needs:`, so none can start (and none can read a `release`-scoped
	# secret or mint an OIDC token) until this approval lands. The
	# `release` environment keeps those secrets, its OIDC Trusted-
	# Publisher scope, and its main-only branch restriction; it just no
	# longer carries a reviewer. Moving the reviewer onto a single-use
	# environment is what collapses the old three approval waves
	# (npm/pypi/vscode, then release, then winget-submit) into one. No
	# checkout, no secrets, no OIDC here — nothing to attack.
	gate:
	needs: [build]
	if: *release_repo_trigger_ok
	runs-on: ubuntu-latest
	environment: release-approval
	steps:
	- name: Record the single release approval
	run: echo "release ${VERSION} approved; publishing every channel"

	vscode:
	# `needs: [build]` for the binaries: the .vsix bundles a binary
	# for every supported platform (build.ts → dist/cli/), so the
	# extension picks the right one at runtime by re-using the
	# @mdsmith/cli resolver. The five binaries come straight from the
	# `build` job's release artifacts via `mdsmith-release build-npm`
	# — the same generator the `npm` job uses — so this job no longer
	# waits on (or couples to) the npm publish.
	needs: [build, gate]
	runs-on: ubuntu-latest
	# MDSMITH_VSIX_PLATFORM_DIR points build.ts at the full
	# build-npm output. It is set at job scope so the run that
	# `vsce package` triggers through the `vscode:prepublish` hook
	# re-stages all five binaries too (build.ts staging is also
	# non-destructive, so a missing env would keep — not wipe — the
	# explicit build's binaries; the env makes it deterministic).
	env:
	MDSMITH_VSIX_PLATFORM_DIR: ${{ github.workspace }}/npm/dist
	# VSCE_PAT and OVSX_PAT are long-lived publisher tokens — see
	# docs/development/release.md for why the `release` environment
	# gates them and what reviewer rules the maintainer should set
	# on it.
	if: *release_repo_trigger_ok
	environment: release
	steps:
	- uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
	with:
	persist-credentials: false
	- uses: ./.github/actions/setup-bun
	- uses: actions/setup-go@7a3fe6cf4cb3a834922a1244abfce67bcef6a0c5 # v6.2.0
	with:
	go-version-file: go.mod
	# zizmor's cache-poisoning rule treats the GitHub Actions
	# tool cache as an unprotected mutation surface in
	# release-context workflows; setup-go would default to
	# caching the module download. Disable it to match the
	# build job above.
	cache: false
	- name: Stamp tracked manifests with the tag
	env:
	VERSION: ${{ env.VERSION }}
	# Stamp rewrites the `version` field in
	# editors/vscode/package.json (the .vsix version) and the
	# one in npm/mdsmith/package.json that build-npm stamps
	# into each generated platform manifest.
	run: go run ./cmd/mdsmith-release stamp "${VERSION#v}"
	- name: Download release artifacts
	uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093 # v4.3.0
	with:
	path: artifacts
	merge-multiple: true
	- name: Build platform packages
	# Reuse the npm generator so the .vsix carries the exact
	# same per-platform binaries the npm channel ships. Output
	# lands in npm/dist/<target>/bin/, which
	# MDSMITH_VSIX_PLATFORM_DIR points build.ts at.
	run: go run ./cmd/mdsmith-release build-npm artifacts npm/dist
	- name: Install extension dependencies
	working-directory: editors/vscode
	# `--ignore-scripts` blocks postinstall / preinstall hooks from
	# every dep in the resolved tree. The mdsmith extension's
	# production deps (vscode-languageclient) and dev deps
	# (@vscode/vsce, typescript, @types/*) are pure-JS and need
	# no install-time hooks — disabling them shrinks the blast
	# radius if a future lockfile update or registry compromise
	# ships a malicious lifecycle script (the TanStack /
	# shai-hulud worm class).
	#
	# No `--frozen-lockfile` here: the Stamp step above just
	# rewrote the @mdsmith/cli optionalDependency to the
	# version this run is publishing, so bun.lock is
	# intentionally out-of-date for that one entry.
	# `--ignore-scripts` still guards the lifecycle-hook
	# surface that the shai-hulud / TanStack worm relies on.
	run: bun install --ignore-scripts
	- name: Run extension unit tests
	working-directory: editors/vscode
	run: bun test
	- name: Compile extension
	working-directory: editors/vscode
	run: bun run build.ts --production
	- name: Package .vsix
	env:
	VERSION: ${{ env.VERSION }}
	working-directory: editors/vscode
	run: \|
	ver="${VERSION#v}"
	bunx --bun @vscode/vsce package --no-dependencies \
	--out "mdsmith-${ver}.vsix"
	# Verify the publisher tokens are set BEFORE the publish steps
	# run. The publishes themselves use `continue-on-error: true`
	# so a transient registry outage does not block the GitHub
	# release. That same flag would also hide an unset/empty
	# secret, so guard misconfiguration here (no continue-on-error)
	# while still letting outages slide on the actual publish.
	- name: Verify Marketplace and Open VSX tokens are set
	env:
	VSCE_PAT: ${{ secrets.VSCE_PAT }}
	OVSX_PAT: ${{ secrets.OVSX_PAT }}
	run: \|
	missing=""
	[ -n "${VSCE_PAT:-}" ] \|\| missing="$missing VSCE_PAT"
	[ -n "${OVSX_PAT:-}" ] \|\| missing="$missing OVSX_PAT"
	if [ -n "$missing" ]; then
	echo "missing required repo secret(s):$missing" >&2
	exit 1
	fi
	- name: Publish to Visual Studio Marketplace
	# The GitHub release .vsix is the documented fallback, so a
	# transient Marketplace outage should not block the release
	# job downstream of this one. Misconfiguration is caught by
	# the preceding verify step, so this only swallows runtime
	# registry errors.
	continue-on-error: true
	env:
	VERSION: ${{ env.VERSION }}
	VSCE_PAT: ${{ secrets.VSCE_PAT }}
	working-directory: editors/vscode
	# Reuse the exact .vsix the artifact upload below ships, so
	# Marketplace, Open VSX, and the GitHub release are byte-
	# identical. The publisher namespace is jeduden — claim it
	# in https://aka.ms/vscode-create-publisher before the first
	# release. PAT scope: Marketplace > Manage. Azure caps PATs
	# at one year; rotate annually and record the date in
	# CLAUDE.md.
	run: \|
	ver="${VERSION#v}"
	bunx --bun @vscode/vsce publish \
	--no-dependencies \
	--packagePath "mdsmith-${ver}.vsix" \
	--pat "$VSCE_PAT"
	- name: Publish to Open VSX
	continue-on-error: true
	env:
	VERSION: ${{ env.VERSION }}
	OVSX_PAT: ${{ secrets.OVSX_PAT }}
	working-directory: editors/vscode
	# Open VSX is the registry VSCodium, Cursor, Theia, and
	# Gitpod query. Claim the jeduden namespace on
	# https://open-vsx.org and store the publisher token as the
	# OVSX_PAT secret before the first release. Rotate annually.
	run: \|
	ver="${VERSION#v}"
	bunx --bun ovsx publish \
	--packagePath "mdsmith-${ver}.vsix" \
	--pat "$OVSX_PAT"
	- uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4.6.2
	with:
	name: mdsmith-vscode-extension
	path: editors/vscode/mdsmith-*.vsix

	obsidian:
	# Plan 217. The Obsidian plugin ships ONE WASM artifact (not a
	# per-platform binary), so it does not depend on the `build` matrix.
	# It compiles the engine to WebAssembly, builds the plugin, and zips
	# dist/ as mdsmith-obsidian-<version>.zip. The `release` job
	# downloads it with the other artifacts and the `mdsmith-*` globs
	# there cover it for the GitHub release attachment, the checksum
	# file, the SLSA provenance, and the cosign signature.
	#
	# No publisher tokens and no `release` environment: the only channel
	# is GitHub Releases (plan 217 Non-Goals), so there is nothing to
	# gate. The plugin manifests (editors/obsidian/{manifest,package}.json)
	# are in the tracked-manifest set, so `mdsmith-release stamp` rewrites
	# their dev sentinel to the release version alongside the rest of the
	# tracked set; only this job's zip carries the result.
	needs: [preflight]
	if: *release_repo_trigger_ok
	runs-on: ubuntu-latest
	steps:
	- uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
	with:
	persist-credentials: false
	- uses: ./.github/actions/setup-bun
	- uses: actions/setup-go@7a3fe6cf4cb3a834922a1244abfce67bcef6a0c5 # v6.2.0
	with:
	go-version-file: go.mod
	cache: false
	- name: Stamp the manifests with the release version
	env:
	VERSION: ${{ env.VERSION }}
	# Runtime logic lives in mdsmith-release per
	# docs/development/release-tooling.md. stamp rewrites every
	# tracked manifest's dev sentinel to the release tag (the obsidian
	# manifest.json/package.json among them); the checkout is
	# discarded after the run, so only the zip built below ships the
	# stamped files.
	run: go run ./cmd/mdsmith-release stamp "${VERSION#v}"
	- name: Install plugin dependencies
	working-directory: editors/obsidian
	# --ignore-scripts neutralizes install-time hooks (see the npm
	# job and release.md). No --frozen-lockfile: the stamp above
	# rewrote package.json's version, so bun.lock is intentionally
	# out of date for that field.
	run: bun install --ignore-scripts
	- name: Run plugin unit tests
	working-directory: editors/obsidian
	run: bun test --preload ./src/test-setup.ts
	- name: Build the engine to WebAssembly
	run: bash cmd/mdsmith-wasm/build.sh
	- name: Build the plugin
	working-directory: editors/obsidian
	env:
	MDSMITH_OBSIDIAN_WASM_DIR: ${{ github.workspace }}/cmd/mdsmith-wasm/dist
	run: bun run build.ts --production
	- name: Package the release zip
	# Runtime logic lives in mdsmith-release per
	# docs/development/release-tooling.md. The stamp step above
	# rewrote dist's manifest.json to the release version, so
	# package-obsidian reads the version from there and writes
	# mdsmith-obsidian-<version>.zip with the five files Obsidian
	# loads, flat, via archive/zip. outDir is editors/obsidian so
	# the upload glob below matches.
	run: go run ./cmd/mdsmith-release package-obsidian editors/obsidian/dist editors/obsidian
	- uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4.6.2
	with:
	name: mdsmith-obsidian-plugin
	path: editors/obsidian/mdsmith-obsidian-*.zip

	npm:
	needs: [build, gate]
	runs-on: ubuntu-latest
	# See docs/development/release.md for the canonical description
	# of `if:`, `environment:`, OIDC Trusted Publishing scope, and
	# the operational checklist for npmjs.com / pypi.org / GitHub
	# environment configuration. Workflow comments here only record
	# the local intent of each setting.
	if: *release_repo_trigger_ok
	environment: release
	# `id-token: write` lets `npm publish --provenance` mint an OIDC
	# token so the npm registry stamps each tarball with verifiable
	# build metadata pointing at this exact workflow run.
	permissions:
	contents: read
	id-token: write
	steps:
	- uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
	with:
	persist-credentials: false
	- uses: actions/setup-go@7a3fe6cf4cb3a834922a1244abfce67bcef6a0c5 # v6.2.0
	with:
	go-version-file: go.mod
	cache: false
	- uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e # v6.4.0
	with:
	# Node 24 ships npm 11.x. npm Trusted Publishing
	# requires npm >= 11.5; older CLIs silently fall back
	# to token auth and the registry returns 404 for
	# missing-credential publishes (404 instead of 401 so
	# package existence isn't leaked).
	node-version: "24"
	registry-url: "https://registry.npmjs.org"
	- name: Verify npm >= 11.5 for Trusted Publishing
	# Defensive guardrail: even though Node 24 currently ships
	# npm 11.x, a future Node 24 patch could bundle an older
	# CLI. If npm < 11.5 the publish would silently 404.
	run: \|
	actual=$(npm --version)
	echo "npm version: $actual"
	node -e '
	const v = process.argv[1].split(".").map(Number);
	const min = [11, 5, 0];
	for (let i = 0; i < 3; i++) {
	if (v[i] > min[i]) process.exit(0);
	if (v[i] < min[i]) {
	console.error("npm " + process.argv[1] +
	" is too old for Trusted Publishing (need >= 11.5.0)");
	process.exit(1);
	}
	}
	' "$actual"
	- name: Stamp tracked manifests with the tag
	env:
	VERSION: ${{ env.VERSION }}
	run: go run ./cmd/mdsmith-release stamp "${VERSION#v}"
	- name: Download release artifacts
	uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093 # v4.3.0
	with:
	path: artifacts
	merge-multiple: true
	- name: Build platform packages
	run: go run ./cmd/mdsmith-release build-npm artifacts npm/dist
	- name: Publish platform packages
	# Platform packages publish first so the root never advertises
	# an optionalDependency npm cannot find. The root package
	# publishes last, after every platform exists. Auth uses npm
	# Trusted Publishing (OIDC) — see docs/development/release.md
	# for the npmjs.com publisher configuration each of the six
	# packages needs.
	run: \|
	for pkg in npm/dist/*; do
	(cd "$pkg" && npm publish --access public --provenance)
	done
	- name: Stage LICENSE for root package
	# The root @mdsmith/cli package directory has no checked-in
	# LICENSE because the canonical one lives at repo root. npm
	# auto-includes a top-level LICENSE in the published tarball,
	# but only if it sits next to package.json at publish time —
	# so copy it in before `npm publish`. The root LICENSE also
	# carries the vendored neurosnap/sentences MIT notice for
	# internal/punkt/, which is what makes this step legally
	# required for the npm channel.
	run: cp LICENSE npm/mdsmith/LICENSE
	- name: Publish root package
	working-directory: npm/mdsmith
	run: npm publish --access public --provenance

	pypi:
	needs: [build, gate]
	runs-on: ubuntu-latest
	# See docs/development/release.md for the canonical PyPI Trusted
	# Publisher config (workflow + environment scope) and the
	# operational checklist.
	if: *release_repo_trigger_ok
	environment: release
	permissions:
	contents: read
	id-token: write
	steps:
	- uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
	with:
	persist-credentials: false
	- uses: actions/setup-go@7a3fe6cf4cb3a834922a1244abfce67bcef6a0c5 # v6.2.0
	with:
	go-version-file: go.mod
	cache: false
	- uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405 # v6.2.0
	with:
	python-version: "3.12"
	- name: Stamp tracked manifests with the tag
	env:
	VERSION: ${{ env.VERSION }}
	run: go run ./cmd/mdsmith-release stamp "${VERSION#v}"
	- name: Install build tooling
	# `python -m build` and `python -m wheel` orchestrate the
	# wheel build and the platform-tag retag respectively;
	# hatchling is the build backend pyproject.toml selects.
	run: python -m pip install --upgrade build wheel hatchling
	- name: Download release artifacts
	uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093 # v4.3.0
	with:
	path: artifacts
	merge-multiple: true
	- name: Build platform wheels
	run: go run ./cmd/mdsmith-release build-wheels artifacts python/dist
	- name: Publish to PyPI
	uses: pypa/gh-action-pypi-publish@cef221092ed1bacb1cc03d23a2d87d1d172e277b # release/v1
	with:
	packages-dir: python/dist

	release:
	# `flatpak` joins `build`/`vscode` here so the .flatpak bundle it
	# produces is downloaded with the other artifacts and uploaded to
	# the draft before it freezes. The bundle is named with the
	# `mdsmith-` prefix, so the checksum, SLSA attestation, and cosign
	# steps below cover it via the same `mdsmith-*` glob as the raw
	# binaries — no release-job changes beyond this dependency. `obsidian`
	# (plan 217) joins for the same reason: its
	# mdsmith-obsidian-<version>.zip is matched by the `mdsmith-*` globs.
	needs: [build, vscode, obsidian, flatpak, gate]
	runs-on: ubuntu-latest
	# See docs/development/release.md for the rationale on `if:`,
	# `environment:`, and the OIDC + attestations permission set.
	if: *release_repo_trigger_ok
	environment: release
	permissions:
	contents: write
	id-token: write
	attestations: write
	steps:
	- uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
	with:
	persist-credentials: false
	- uses: actions/setup-go@7a3fe6cf4cb3a834922a1244abfce67bcef6a0c5 # v6.2.0
	with:
	go-version-file: go.mod
	cache: false
	- uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093 # v4.3.0
	with:
	merge-multiple: true
	- name: Generate CycloneDX SBOM
	# CycloneDX SBOM of the Go module that produced the release
	# binaries. Runtime logic lives in mdsmith-release per
	# docs/development/release-tooling.md: the tool version is
	# pinned in internal/release/sbom.go and the implementation
	# uses `go run <module>@<pinned>` so no PATH setup beyond
	# the Go toolchain is required. Output is named with the
	# `mdsmith-` prefix so the checksum step below picks it up
	# automatically and the cosign signature covers it
	# transitively. Verify with:
	# sha256sum -c <(grep mdsmith-sbom.cdx.json checksums.txt)
	run: go run ./cmd/mdsmith-release sbom mdsmith-sbom.cdx.json
	- name: Create checksums
	run: sha256sum mdsmith-* > checksums.txt
	- name: Generate SLSA build provenance
	# Attests every binary the build matrix produced (and the
	# .vsix the vscode job uploaded — `mdsmith-*` matches both).
	# Each attestation ties the file's SHA-256 back to this
	# workflow run and the commit it was built from. Consumers
	# verify with:
	# gh attestation verify mdsmith-<plat> -R jeduden/mdsmith
	uses: actions/attest-build-provenance@a2bbfa25375fe432b6a289bc6b6cd05ecd0c4c32 # v4.1.0
	with:
	subject-path: "mdsmith-*"
	- name: Install cosign
	uses: sigstore/cosign-installer@6f9f17788090df1f26f669e9d70d6ae9567deba6 # v4.1.2
	with:
	# Pin cosign to a known v3.x release. The sign-blob step
	# below relies on `--bundle` being the required output
	# path (cosign 3.0.0 promoted it from optional to
	# required); pinning shields the release from a future
	# installer default rolling forward to a major that
	# changes the bundle contract again.
	cosign-release: "v3.0.6"
	- name: Sign checksums with cosign
	# Keyless Sigstore signature on the checksum file. The
	# GitHub OIDC token binds the signature to this exact
	# workflow file at this exact tag, so an attacker who
	# rewrites checksums.txt on the release page can't also
	# forge a matching signature without compromising
	# release.yml on this repo. The bundle file carries both
	# the signature and the signing certificate; cosign 3.x
	# deprecated the separate --output-signature /
	# --output-certificate flags in favor of --bundle.
	# Verify with:
	# cosign verify-blob \
	# --bundle checksums.txt.bundle \
	# --certificate-identity-regexp \
	# "^https://github.com/jeduden/mdsmith/.github/workflows/release.yml@" \
	# --certificate-oidc-issuer \
	# https://token.actions.githubusercontent.com \
	# checksums.txt
	env:
	COSIGN_YES: "true"
	run: \|
	cosign sign-blob \
	--bundle checksums.txt.bundle \
	checksums.txt
	- name: Upload assets to draft release
	# Create the release as a draft so every asset uploads while
	# the release is still mutable. With immutable releases
	# enforced, uploading to an already-published release is
	# rejected — the publish must be the final step.
	#
	# The workflow is dispatched from a branch, not a tag, so the
	# tag does not exist yet: `tag_name` + `target_commitish`
	# make this step create it at the dispatched commit.
	env:
	GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
	uses: softprops/action-gh-release@72f2c25fcb47643c292f7107632f7a47c1df5cd8 # v2.3.2
	with:
	draft: true
	tag_name: ${{ env.VERSION }}
	target_commitish: ${{ github.sha }}
	generate_release_notes: true
	files: \|
	mdsmith-*
	checksums.txt
	checksums.txt.bundle
	- name: Publish release
	# Flip the fully-populated draft to published as the final
	# atomic step, yielding an immutable release. Runtime logic
	# lives in mdsmith-release per
	# docs/development/release-tooling.md.
	env:
	RELEASE_TAG: ${{ env.VERSION }}
	GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
	run: go run ./cmd/mdsmith-release publish-release

	# Build the self-hosted .flatpak bundle. Like `vscode`, this chains
	# off `build` (not `release`) and hands its artifact to the `release`
	# job, which attaches `mdsmith-x86_64.flatpak` to the draft before it
	# freezes — uploading to an immutable, already-published release is
	# rejected. The bundle is built from the freshly built x86_64 binary
	# via flatpak-builder, so it needs no published download URL. x86_64
	# only: flatpak-builder targets the runner's native arch and
	# cross-building aarch64 under emulation is not worth it for this
	# channel (aarch64 Linux uses the binary, npm, or PyPI channels).
	# The job carries no secrets, so it runs without the `release`
	# environment gate. See docs/development/release-channels/flatpak.md.
	flatpak:
	needs: [build]
	runs-on: ubuntu-latest
	# Bound the heavy steps (apt install + ~hundreds-of-MB Flathub
	# runtime pull + flatpak-builder) so a stuck download cannot hold
	# the release-gating job to the 6h default.
	timeout-minutes: 20
	if: *release_repo_trigger_ok
	steps:
	- uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
	with:
	persist-credentials: false
	- uses: actions/setup-go@7a3fe6cf4cb3a834922a1244abfce67bcef6a0c5 # v6.2.0
	with:
	go-version-file: go.mod
	cache: false
	- name: Download release artifacts
	uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093 # v4.3.0
	with:
	path: artifacts
	merge-multiple: true
	- name: Stage manifest and binaries
	# build-flatpak writes the flatpak-builder manifest and copies
	# the Linux binaries it references (via local `path:` sources)
	# into flatpak-build/, so the bundle builds without a release
	# download URL.
	run: go run ./cmd/mdsmith-release build-flatpak artifacts flatpak-build
	- name: Install flatpak-builder and the freedesktop runtime
	run: \|
	sudo apt-get update
	sudo apt-get install -y flatpak flatpak-builder
	# Ubuntu 24.04 restricts unprivileged user namespaces via
	# AppArmor, which blocks the bubblewrap sandbox that
	# flatpak-builder and `flatpak run` rely on. Re-enable it on
	# the runner (best-effort: the knob is absent on older
	# kernels, where the restriction does not exist).
	sudo sysctl -w kernel.apparmor_restrict_unprivileged_userns=0 \|\| true
	flatpak remote-add --user --if-not-exists \
	flathub https://flathub.org/repo/flathub.flatpakrepo
	- name: Build the bundle
	# flatpak-builder pulls the org.freedesktop 24.08 Platform/SDK
	# from flathub, builds the app into a local OSTree repo, and
	# build-bundle packs it into a single file. --runtime-repo
	# records flathub so `flatpak install ./mdsmith-x86_64.flatpak`
	# can offer the runtime if the host lacks it.
	# --disable-rofiles-fuse avoids the rofiles-fuse mount, which is
	# fragile under the runner's restricted FUSE.
	run: \|
	flatpak-builder --user --install-deps-from=flathub \
	--disable-rofiles-fuse --force-clean --repo=flatpak-repo \
	flatpak-build-dir flatpak-build/io.github.jeduden.mdsmith.yml
	flatpak build-bundle \
	--runtime-repo=https://flathub.org/repo/flathub.flatpakrepo \
	flatpak-repo mdsmith-x86_64.flatpak io.github.jeduden.mdsmith
	- name: Verify the bundle installs and reports the right version
	# No other job exercises this channel (smoke-test runs in
	# flatpak-less containers), so confirm the bundle installs and
	# `mdsmith version` matches the tag before it ships. A broken
	# bundle fails the job — and, since `release` needs it, blocks
	# the release rather than shipping a dud asset.
	env:
	VERSION: ${{ env.VERSION }}
	run: \|
	flatpak install --user -y ./mdsmith-x86_64.flatpak
	# Take the last stdout line so a first-run portal/sandbox
	# notice cannot break the exact-match check.
	got=$(flatpak run io.github.jeduden.mdsmith version \| tail -n1)
	want="mdsmith ${VERSION}"
	if [ "$got" != "$want" ]; then
	echo "flatpak bundle version mismatch: got '$got', want '$want'" >&2
	exit 1
	fi
	echo "flatpak bundle: $got"
	- uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4.6.2
	with:
	name: mdsmith-flatpak-bundle
	path: mdsmith-x86_64.flatpak

	smoke-test:
	# Wait until every channel is on the new version before checking
	# — the npm and PyPI registries can take ~60s to surface a fresh
	# publish, so the channel-specific install commands re-run if the
	# registry briefly returns the previous version.
	needs: [npm, pypi, release]
	strategy:
	fail-fast: false
	matrix:
	include:
	- channel: npm
	# node:lts (debian-slim) ships bash, so the install step
	# runs under the action's default `bash -e` shell. Alpine
	# would force `shell: sh` everywhere because busybox has
	# no bash before `apk add` runs.
	container: node:lts
	install: \|
	# npm registry propagation can lag the publish by ~60s,
	# so retry with backoff until the just-published version
	# is resolvable. Mirrors the pip retry loop below.
	ok=0
	for attempt in 1 2 3 4 5; do
	if npm install -g --force "@mdsmith/cli@${VERSION#v}"; then
	ok=1; break
	fi
	sleep 15
	done
	if [ "$ok" -ne 1 ]; then
	echo "npm install never succeeded after 5 attempts" >&2
	exit 1
	fi
	run: mdsmith version
	- channel: pip
	container: python:3.12-slim
	install: \|
	python -m pip install --upgrade pip
	# `--upgrade` forces pip to pick the just-published
	# wheel rather than a cached older one.
	ok=0
	for attempt in 1 2 3 4 5; do
	if python -m pip install --upgrade "mdsmith==${VERSION#v}"; then
	ok=1; break
	fi
	sleep 15
	done
	if [ "$ok" -ne 1 ]; then
	echo "pip install never succeeded after 5 attempts" >&2
	exit 1
	fi
	run: mdsmith version
	- channel: mise
	container: jdxcode/mise:latest
	# `github:jeduden/mdsmith@VER` resolves the binary directly
	# off the GitHub release the same `release` job above
	# just published. The shorter `mdsmith@VER` form depends
	# on the mise-plugins/registry follow-up; until that PR
	# lands the smoke-test would fail on every release, so
	# exercise the form that works today.
	install: \|
	ok=0
	for attempt in 1 2 3 4 5; do
	if mise use -g "github:jeduden/mdsmith@${VERSION#v}"; then
	ok=1; break
	fi
	sleep 15
	done
	if [ "$ok" -ne 1 ]; then
	echo "mise install never succeeded after 5 attempts" >&2
	exit 1
	fi
	run: \|
	eval "$(mise activate bash --shims)"
	mdsmith version
	- channel: mise-registry
	# The prefix-less `mise use mdsmith@VER` form (no `ubi:`,
	# `github:`, or other backend prefix) resolves only once the
	# jdx/mise curated registry lists mdsmith — the plan 145
	# follow-up PR. Until that entry merges this command fails on
	# every release, so the install step is BEST-EFFORT: it
	# retries, then on repeated failure emits a `::warning::`,
	# writes `skipped=true` (which the shared Verify step keys
	# off, so it does not run `mdsmith version` against a binary
	# that was never installed), and exits 0 rather than
	# reddening the release. The day the registry PR lands this
	# entry starts passing with no workflow change, and
	# `mise-registry` is NOT in RequiredSmokeChannels so the
	# gate never demands it green.
	container: jdxcode/mise:latest
	install: \|
	ok=0
	for attempt in 1 2 3 4 5; do
	if mise use -g "mdsmith@${VERSION#v}"; then
	ok=1; break
	fi
	sleep 15
	done
	if [ "$ok" -ne 1 ]; then
	echo "::warning::bare 'mise use mdsmith@${VERSION#v}' did not resolve; the jdx/mise registry entry (plan 145) has not merged yet. The 'mise' channel above (ubi: backend) still verifies the binary."
	echo "skipped=true" >> "$GITHUB_OUTPUT"
	exit 0
	fi
	run: \|
	eval "$(mise activate bash --shims)"
	mdsmith version
	- channel: asdf
	# `asdf install mdsmith VER` through the explicit plugin URL
	# (jeduden/asdf-mdsmith). This works on day one — no registry
	# follow-up — so a break here must fail the release, hence
	# `asdf` is in RequiredSmokeChannels. The plugin's bin/list-all
	# reads this repo's git tags, bin/download fetches the matching
	# release asset, and bin/install verifies it against
	# checksums.txt; the ubuntu image carries git+curl, which is
	# all the plugin needs.
	container: ubuntu:latest
	install: \|
	apt-get update
	apt-get install -y --no-install-recommends \
	git curl ca-certificates stow unzip
	git clone https://github.com/asdf-vm/asdf.git \
	--branch v0.14.1 "$HOME/.asdf"
	export ASDF_DIR="$HOME/.asdf"
	. "$HOME/.asdf/asdf.sh"
	asdf plugin add mdsmith \
	https://github.com/jeduden/asdf-mdsmith.git
	# The plugin's bin/list-all reads tags off this repo, but a
	# freshly pushed tag can take a moment to surface; retry like
	# the registry loops above.
	ok=0
	for attempt in 1 2 3 4 5; do
	if asdf install mdsmith "${VERSION#v}"; then
	ok=1; break
	fi
	sleep 15
	done
	if [ "$ok" -ne 1 ]; then
	echo "asdf install never succeeded after 5 attempts" >&2
	exit 1
	fi
	asdf global mdsmith "${VERSION#v}"
	run: \|
	export ASDF_DIR="$HOME/.asdf"
	. "$HOME/.asdf/asdf.sh"
	mdsmith version
	- channel: go
	# Resolve the freshly tagged module through proxy.golang.org
	# and compile it, exactly as `go install` users do — the
	# path that shipped broken in v0.40.0 (a go.mod replace
	# directive is fatal only here) and that no pre-release job
	# exercises. TestRootGoModStaysInstallable guards the
	# go.mod shape pre-merge; this entry proves the published
	# tag end-to-end. The binary stamps its version from the
	# module tag, so the shared assertion below just works;
	# golang:1.25 ships bash and has /go/bin on PATH.
	container: golang:1.25
	install: \|
	# proxy.golang.org fetches a brand-new tag on first
	# request, but a cold edge can briefly serve 404/410 for
	# it; retry with backoff like the registry loops above.
	ok=0
	for attempt in 1 2 3 4 5; do
	if go install "github.com/jeduden/mdsmith/cmd/mdsmith@${VERSION}"; then
	ok=1; break
	fi
	sleep 15
	done
	if [ "$ok" -ne 1 ]; then
	echo "go install never succeeded after 5 attempts" >&2
	exit 1
	fi
	run: mdsmith version
	runs-on: ubuntu-latest
	container: ${{ matrix.container }}
	steps:
	- name: Install
	id: install
	run: ${{ matrix.install }}
	- name: Verify version
	# A best-effort channel (mise-registry today) soft-skips its
	# install with `skipped=true` when the upstream registry entry
	# does not exist yet; verifying a binary that was never
	# installed would fail with exit 127, so skip alongside it.
	# Hard install failures are covered by the implicit success()
	# in this expression — do not add continue-on-error to the
	# Install step, or a failed install would fall through to here
	# with no skipped output and re-fail as a confusing exit 127.
	if: steps.install.outputs.skipped != 'true'
	run: \|
	got=$(${{ matrix.run }})
	want="mdsmith ${VERSION}"
	if [ "$got" != "$want" ]; then
	echo "channel=${{ matrix.channel }}: got '$got', want '$want'" >&2
	exit 1
	fi
	echo "channel=${{ matrix.channel }}: $got"

	# Nudge the Homebrew tap to bump its formula to this version right
	# away. Best-effort: the tap at jeduden/homebrew-mdsmith also
	# self-bumps on a daily schedule, so a missing token or a failed
	# dispatch never blocks a release. The token is a fine-grained PAT
	# with Contents: write on the tap repo, stored as the
	# HOMEBREW_TAP_DISPATCH_TOKEN secret on the `release` environment —
	# reviewer-gated like the publish jobs and unreadable before the
	# `gate` approval, hence `environment: release` + `needs: gate`.
	notify-homebrew-tap:
	needs: [release, gate]
	if: *release_repo_trigger_ok
	runs-on: ubuntu-latest
	environment: release
	steps:
	- name: Dispatch a formula bump to the tap
	env:
	GH_TOKEN: ${{ secrets.HOMEBREW_TAP_DISPATCH_TOKEN }}
	VERSION: ${{ env.VERSION }}
	run: \|
	if [ -z "${GH_TOKEN:-}" ]; then
	echo "HOMEBREW_TAP_DISPATCH_TOKEN unset; the tap will self-bump on its daily schedule."
	exit 0
	fi
	gh api repos/jeduden/homebrew-mdsmith/dispatches \
	-f event_type=mdsmith-release \
	-f "client_payload[version]=${VERSION#v}"

	# Nudge the Scoop bucket to bump its manifest to this version right
	# away. Best-effort: the bucket at jeduden/scoop-mdsmith also
	# self-bumps via its `checkver` + `autoupdate` blocks on a daily
	# schedule, so a missing token or a failed dispatch never blocks a
	# release. The token is a fine-grained PAT with Contents: write on
	# the bucket repo, stored as the SCOOP_BUCKET_DISPATCH_TOKEN secret
	# on the `release` environment — reviewer-gated like the publish jobs
	# and unreadable before the `gate` approval, hence
	# `environment: release` + `needs: gate`.
	notify-scoop-bucket:
	needs: [release, gate]
	if: *release_repo_trigger_ok
	runs-on: ubuntu-latest
	environment: release
	steps:
	- name: Dispatch a manifest bump to the Scoop bucket
	env:
	GH_TOKEN: ${{ secrets.SCOOP_BUCKET_DISPATCH_TOKEN }}
	VERSION: ${{ env.VERSION }}
	run: \|
	if [ -z "${GH_TOKEN:-}" ]; then
	echo "::notice::SCOOP_BUCKET_DISPATCH_TOKEN unset; the bucket will self-bump via checkver."
	exit 0
	fi
	gh api repos/jeduden/scoop-mdsmith/dispatches \
	-f event_type=mdsmith-release \
	-f "client_payload[version]=${VERSION#v}"

	# Submit the WinGet manifest for this release. Best-effort: if
	# WINGET_PR_TOKEN is unset, komac cannot be fetched, or the
	# submission fails, the job logs a notice/warning and exits 0 so
	# the release is never blocked. komac builds the manifest from the
	# published Windows installer URL and opens the PR — the same
	# approach peers like mise use (via the winget-releaser action).
	# `komac update` targets an existing package, so the first version
	# is bootstrapped manually with `mdsmith-release
	# render-winget-manifest`, mirroring how render-scoop-manifest
	# bootstraps the Scoop bucket. The token is a PAT with fork+PR
	# rights on microsoft/winget-pkgs, stored as the WINGET_PR_TOKEN
	# repo secret gated by the `release` environment (same gate as the
	# other publish jobs) so a stolen token cannot silently submit
	# manifests without reviewer approval.
	winget-submit:
	needs: [release, gate]
	if: *release_repo_trigger_ok
	runs-on: ubuntu-latest
	environment: release
	steps:
	- name: Submit the WinGet manifest via komac
	env:
	GITHUB_TOKEN: ${{ secrets.WINGET_PR_TOKEN }}
	VERSION: ${{ env.VERSION }}
	run: \|
	if [ -z "${GITHUB_TOKEN:-}" ]; then
	echo "::notice::WINGET_PR_TOKEN unset; skipping WinGet submission."
	exit 0
	fi
	# Best-effort past this point: a WinGet hiccup must never
	# fail an otherwise-successful release, so each fallible
	# step logs a warning and exits 0.
	KOMAC_VERSION="2.10.0"
	KOMAC_SHA256="523a5c4d685741f540a403e329581ab42c30e2db9b3dd1dd90389f7eefe8a3ba"
	if ! curl -fsSL --max-time 120 --connect-timeout 15 \
	"https://github.com/russellbanks/Komac/releases/download/v${KOMAC_VERSION}/komac-${KOMAC_VERSION}-x86_64-unknown-linux-gnu.tar.gz" \
	-o /tmp/komac.tar.gz; then
	echo "::warning::could not download komac; skipping WinGet submission."
	exit 0
	fi
	if ! echo "${KOMAC_SHA256} /tmp/komac.tar.gz" \| sha256sum -c -; then
	echo "::warning::komac checksum mismatch; skipping WinGet submission."
	exit 0
	fi
	if ! tar -xzf /tmp/komac.tar.gz -C /usr/local/bin/ komac; then
	echo "::warning::could not extract komac; skipping WinGet submission."
	exit 0
	fi
	installer="https://github.com/jeduden/mdsmith/releases/download/${VERSION}/mdsmith-windows-amd64.exe"
	if ! komac update jeduden.mdsmith \
	--version "${VERSION#v}" \
	--urls "${installer}" \
	--submit; then
	echo "::warning::komac submission failed; submit the WinGet PR manually (see docs/development/release-channels/winget.md)."
	exit 0
	fi

	# A tool release also ships the website. The deploy itself lives
	# in pages.yml (its own workflow, also triggered by docs-only
	# pushes to main and by manual workflow_dispatch); this job calls
	# it with the release version so the published site shows the new
	# version. Gated on `release` so the site is deployed only after
	# the release has been frozen — the draft is published and
	# immutable — so mdsmith.dev never advertises a version whose
	# GitHub release does not yet exist. `release` transitively
	# depends on `npm` (release -> vscode -> npm), so a failed npm
	# publish also blocks this deploy. That is intentional: with no
	# frozen release there is no version to ship the site for. `pypi`
	# is not in the release chain, so a PyPI outage does not block it.
	#
	# Also needs `benchmark-publish`: that job re-measures the
	# cross-tool benchmark and uploads the fragments as the
	# `benchmark-numbers` artifact, which pages.yml downloads and bakes
	# into the published performance page. That dependency is what makes
	# benchmark publication a prerequisite for website publication — the
	# site deploy never runs ahead of the numbers it is meant to show,
	# so every release ships its own freshly-measured figures rather
	# than the committed snapshot. A benchmark MEASUREMENT failure
	# blocks this deploy (no fragments to bake); a perf REGRESSION does
	# not — that trips the separate bench-regression-gate, which pages
	# does not depend on, so an honest-but-slower release still ships
	# its site.
	pages:
	needs: [release, benchmark-publish]
	if: *release_repo_trigger_ok
	permissions:
	contents: read
	pages: write
	id-token: write
	uses: ./.github/workflows/pages.yml
	with:
	version: ${{ inputs.version }}
	# The artifact benchmark-publish uploads in this same run;
	# pages.yml downloads it and bakes the fragments into the
	# published performance page so the site shows release numbers.
	benchmark-artifact: benchmark-numbers

	# Re-measure the cross-tool benchmark once per release, then publish
	# the numbers two ways: (1) the `benchmark-numbers` artifact the
	# `pages` job bakes into the published site, so the release ships its
	# own fresh figures; (2) a push of the numbers and the rendered
	# benchmark page to the orphan `assets` branch (the branch demo.yml
	# and benchmark.yml already use), which the README links to. It runs
	# AFTER `release`.
	#
	# GitHub Actions cannot open PRs in this repo (the "Allow GitHub
	# Actions to create and approve pull requests" setting is off and
	# stays off — that denial turned a fully-published v0.36.0 into a red
	# release run), but it CAN push to `assets`. So the numbers are
	# published by pushing to `assets`, never by a PR into protected main;
	# the committed in-repo snapshot is refreshed separately via run.sh.
	#
	# This job succeeds whenever the MEASUREMENT succeeds, even on a perf
	# regression: `pages` needs this job, and a regressed-but-honest
	# release must still ship its site. The hard regression signal lives
	# in the separate `bench-regression-gate` below, which fails visibly
	# on a real slowdown but does not block the deploy. A measurement or
	# cross-tool-fetch failure here DOES fail the job (and so blocks
	# `pages`), because there are then no fresh numbers. The assets push
	# is best-effort: `pages` consumes the uploaded artifact, not the
	# push, so a push race or failure warns but never blocks the site.
	benchmark-publish:
	needs: [release]
	if: *release_repo_trigger_ok
	runs-on: ubuntu-latest
	timeout-minutes: 60
	# Serialize against demo.yml and benchmark.yml: all three rewrite
	# disjoint subtrees on the same orphan `assets` ref, so a concurrent
	# writer would lose its push to non-fast-forward rejection. The
	# retry-with-refetch loop in the publish step is the second defense.
	concurrency:
	group: assets-branch
	cancel-in-progress: false
	# contents: write to push the numbers to the orphan `assets` branch
	# (never to protected main). No pull-requests permission: this job
	# publishes by pushing to `assets`, not by opening a PR.
	permissions:
	contents: write
	steps:
	- uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
	with:
	# Never persist the token in git config; the push step
	# authenticates explicitly via a one-shot, masked header.
	persist-credentials: false
	# Full clone so the publish step's `git fetch origin assets`
	# resolves refs/remotes/origin/assets. The default single-
	# branch shallow checkout tracks only main, so the subsequent
	# `git checkout -B assets origin/assets` would die — and inside
	# the `until` loop that failure is swallowed, leaving the job
	# green while it never publishes. Matches the peer assets
	# publishers in benchmark.yml and demo.yml.
	fetch-depth: 0
	- uses: actions/setup-go@7a3fe6cf4cb3a834922a1244abfce67bcef6a0c5 # v6.2.0
	with:
	go-version-file: go.mod
	cache: false
	- uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e # v6.4.0
	with:
	# markdownlint-cli2 installs via `npm ci` from the committed
	# docs/research/benchmarks/npm/ lockfile.
	node-version: "24"
	- name: Snapshot the committed baseline
	# The committed data/ is the previous release's numbers. Keep a
	# copy so bench-check can compare the fresh ratios against it
	# after the measurement overwrites data/ in place.
	run: \|
	# rm first so a re-run on a persistent runner replaces the
	# baseline rather than nesting it under /tmp/baseline-data/data.
	rm -rf /tmp/baseline-data
	cp -r docs/research/benchmarks/data /tmp/baseline-data
	- name: Re-measure the cross-tool benchmark
	run: go run ./cmd/mdsmith-release bench /tmp/mdsmith-bench
	- name: Normalize the freshly measured fragments
	# Normalize the gen_fragments.py tables to the gate's canonical
	# form (the same step benchmark.yml runs). No host page is
	# re-spliced here: the pages job bakes performance.md from the
	# artifact at deploy time, and the README links to
	# results.fragment.md directly.
	run: \|
	go run ./cmd/mdsmith fix \
	docs/research/benchmarks/results.fragment.md \
	docs/research/benchmarks/headline.fragment.md
	- name: Stage the benchmark-numbers artifact
	# Two fragments feed the pages job's site bake; the fresh and
	# baseline data dirs feed bench-regression-gate. Uploaded before
	# the assets push so the artifact every consumer needs exists
	# even if the best-effort push later races or fails.
	run: \|
	mkdir -p artifacts/bench/data artifacts/bench/baseline-data
	cp docs/research/benchmarks/headline.fragment.md \
	docs/research/benchmarks/results.fragment.md \
	artifacts/bench/
	cp docs/research/benchmarks/data/*.json artifacts/bench/data/
	cp /tmp/baseline-data/*.json artifacts/bench/baseline-data/
	- uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4.6.2
	with:
	name: benchmark-numbers
	path: artifacts/bench
	retention-days: 7
	if-no-files-found: error
	- name: Publish the numbers to the assets branch
	# GitHub Actions cannot open PRs here, but it can push to the
	# orphan `assets` branch. Push this release's data + fragments
	# there, so the README's [bench-live] link target
	# (assets/benchmarks/results.fragment.md) shows the release's
	# numbers. This job OWNS assets/benchmarks/; demo.yml owns
	# assets/demo.gif and benchmark.yml owns assets/benchmarks-drift/,
	# so the three subtrees are disjoint. Subtree-safe and
	# best-effort: it rewrites only assets/benchmarks/, commits only
	# on change, retries a push race, and on repeated failure warns
	# rather than failing the job — `pages` needs the artifact
	# uploaded above, not this push.
	shell: bash
	env:
	GH_TOKEN: ${{ github.token }}
	run: \|
	set -euo pipefail
	git config user.name "github-actions[bot]"
	git config user.email "41898282+github-actions[bot]@users.noreply.github.com"

	# Stage the subtree before switching branches: the raw data and
	# the two fragments. results.fragment.md is the README's link
	# target; both render as clean tables with no inner links to
	# 404 on the assets branch.
	rm -rf /tmp/bench-assets
	mkdir -p /tmp/bench-assets/data
	cp docs/research/benchmarks/results.fragment.md \
	docs/research/benchmarks/headline.fragment.md \
	/tmp/bench-assets/
	cp docs/research/benchmarks/data/*.json /tmp/bench-assets/data/

	# The push authenticates via a masked http.extraheader (checkout
	# ran with persist-credentials: false).
	auth_header=$(printf 'x-access-token:%s' "$GH_TOKEN" \| base64 -w0)
	echo "::add-mask::$auth_header"

	# set -e is ignored inside a function run as an `until`
	# condition, so a transient git failure returns non-zero and is
	# retried rather than aborting the step (bash conditional ctx).
	publish_once() {
	if git ls-remote --exit-code origin refs/heads/assets >/dev/null 2>&1; then
	git fetch origin assets
	git checkout -f -B assets origin/assets
	else
	# First ever publish: unborn branch, no siblings yet.
	git checkout --orphan assets
	git rm -r --cached . >/dev/null 2>&1 \|\| true
	fi
	# Replace only our subtree; leave assets/demo.gif (demo.yml's)
	# exactly as it was. Commit only when the numbers changed.
	rm -rf assets/benchmarks
	mkdir -p assets/benchmarks
	cp -R /tmp/bench-assets/. assets/benchmarks/
	git add assets/benchmarks
	if git diff --staged --quiet; then
	echo "benchmark numbers unchanged -- nothing to push"
	return 0
	fi
	git commit -m "bench: publish ${VERSION} cross-tool benchmark numbers"
	git -c "http.https://github.com/.extraheader=AUTHORIZATION: basic ${auth_header}" \
	push -u origin assets
	}

	attempt=1
	max_attempts=5
	backoff=2
	until publish_once; do
	if [ "$attempt" -ge "$max_attempts" ]; then
	echo "::warning::could not publish benchmark numbers to the assets branch after $max_attempts attempts. The website deploy is not blocked (it uses the uploaded benchmark-numbers artifact)."
	exit 0
	fi
	echo "push race on assets branch; retry $attempt/$max_attempts after ${backoff}s"
	sleep "$backoff"
	attempt=$((attempt + 1))
	backoff=$((backoff * 2))
	done

	# Hard regression gate, split out of benchmark-publish so a real
	# slowdown fails visibly WITHOUT blocking the website deploy: `pages`
	# needs `benchmark-publish`, not this job. It re-runs the ratio-based
	# bench-check over the artifact's baseline-vs-fresh data — mdsmith vs
	# mado within each run, so runner speed and the growing corpus cancel
	# and only a real relative slowdown trips it. Reading the data from
	# the artifact (rather than re-measuring) keeps the gate's verdict
	# consistent with the numbers benchmark-publish actually shipped.
	bench-regression-gate:
	needs: [benchmark-publish]
	if: *release_repo_trigger_ok
	runs-on: ubuntu-latest
	steps:
	- uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
	with:
	persist-credentials: false
	- uses: actions/setup-go@7a3fe6cf4cb3a834922a1244abfce67bcef6a0c5 # v6.2.0
	with:
	go-version-file: go.mod
	cache: false
	- uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093 # v4.3.0
	with:
	name: benchmark-numbers
	path: /tmp/bench-numbers
	- name: Compare the mdsmith-vs-mado ratio against the baseline
	# Non-zero exit is a real relative slowdown or unreadable data
	# (the verdict says which); either fails this gate so it is
	# visible, but the website deploy already proceeded in parallel.
	run: \|
	go run ./cmd/mdsmith-release bench-check \
	/tmp/bench-numbers/baseline-data \
	/tmp/bench-numbers/data

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Release #110

Workflow file

Release #110

Uh oh!

Workflow file for this run