Publish releases from a manual pipeline

[jgfoster]

Follows the review suggestion on the release instructions: make publishing something a (manual) pipeline can run.

Stacked on #551. Based on docs/publishing-a-release because it rewrites the document that PR adds, so it targets that branch rather than main. Merge #551 first and this retargets to main cleanly.

The split

The version bump and the changelog stay human, as you guessed — promoting [Unreleased] to a dated section, and sweeping main for changes that never wrote an entry, are editorial calls. Everything after that is mechanical:

1. Release PR (human) — npm version, changelog promotion and sweep. Merges through the queue like anything else.
2. Release workflow (workflow_dispatch) — verify, package, publish, wait, tag, announce. Only ever publishes a commit already on main and already green.

Inputs are version, ref (default main), and dry-run, which runs every check and builds the .vsix without touching either registry.

What it refuses to do

Pre-flight, before any credential is touched or any reviewer is asked to approve: the ref must be an ancestor of main; package.json must be at the requested version; CHANGELOG.md must have a dated ## [X.Y.Z] - YYYY-MM-DD section; no vX.Y.Z tag may exist; and the newest ci-complete check run on that exact commit must have concluded success.

The release deliberately does not re-run lint/compile/test. The merge queue already ran them on that commit across both platforms and every GemStone version in .gemstone-integration-releases.json, plus the Node floor, and ran npm run package — a stronger gate than one run here could be. What matters is that it passed, so the workflow checks that instead of re-deriving it.

Two things the pipeline does that the manual process could not

One artifact, everywhere. The .vsix is built once and published as-is to both registries via --packagePath, then attached to the GitHub Release. The artifact you can download from the run, the two the registries serve, and the one on the Release are the same bytes. Run by hand, each publish command repackages from source, so the local .vsix is not what gets uploaded.

It waits. Both CLIs print success when the upload is accepted, but the version takes ~2–22 minutes to become queryable and either registry can lead — this cost a misdiagnosis during 1.8.11. scripts/await-published-version.sh polls both and states plainly that a timeout is propagation, not a failed publish, so re-publishing is not the fix.

Tagging happens only after both registries are serving the version, so a failed or half-finished publish leaves no tag to clean up and the run can just be repeated; --skip-duplicate on both commands makes that safe.

scripts/changelog-section.sh is used twice — as the pre-flight guard and as the source of the Release notes — so the check and the published text cannot disagree about which section belongs to a version.

Needs one-time setup before the first real run

The workflow is inert until this exists:

1. A release environment (Settings → Environments).
2. Required reviewers on it. This is what makes the approval step a real gate and where the audit trail of who released what comes from. Without it, anyone who can run a workflow can publish.
3. VSCE_PAT and OVSX_PAT as environment secrets, not repository secrets, so no other workflow can reach them.

Worth flagging explicitly, since it's a governance change rather than a mechanical one: this repo currently stores no third-party secrets — only the automatic GITHUB_TOKEN. These would be the first, and because Azure DevOps PATs are personal and expire (a year at most), they are one person's identity acting for the org and they expire silently. The workflow verifies both before building anything, so an expired token fails in seconds rather than halfway through, but they still need an owner who rotates them.

Also new: the repo has no GitHub Releases today. This starts creating them, with the changelog section as the notes and the .vsix attached. Easy to drop that step if you'd rather not adopt the convention.

Releasing by hand stays documented as a fallback — the pipeline is the normal path, not the only one.

Verification

Checked against the same three gates CI applies, all clean on the new files: scripts/lint-workflow-timeouts.sh, actionlint (with shellcheck on every run: block and both new scripts), and zizmor — no ${{ }} reaches a run: script, actions are pinned to SHAs, persist-credentials: false throughout (the tag is created through the API rather than pushed), and permissions are contents: read at the top with contents: write only on the publish job.

Both scripts were exercised against the live registries and the real changelog: changelog-section.sh extracts 1.8.14, stops at the next heading, and rejects an unpromoted version; await-published-version.sh confirms 1.8.14 on both registries and produces the propagation guidance on timeout. The ci-complete selection was checked against a real commit carrying two runs.

lint, format:check, compile and npm test pass (client 452 files / 7294 tests, server 322, mcp-server 92).

The workflow itself cannot be end-to-end tested without publishing a version; dry-run exists so its first real exercise costs nothing.

🤖 Generated with Claude Code