From e39386e90f45c2c7a5a17b3224c2c260b2a8a095 Mon Sep 17 00:00:00 2001 From: Dennis Huebner Date: Fri, 28 Aug 2026 14:09:28 +0200 Subject: [PATCH] Set up trusted publishing Fixes #59 --- .github/workflows/publish-next.yml | 56 ++++++++++ .github/workflows/publish.yml | 56 ++++++++++ AGENTS.md | 4 +- RELEASING.md | 171 +++++++++++++++++++++++++++++ releasing.md | 84 -------------- 5 files changed, 285 insertions(+), 86 deletions(-) create mode 100644 .github/workflows/publish-next.yml create mode 100644 .github/workflows/publish.yml create mode 100644 RELEASING.md delete mode 100644 releasing.md diff --git a/.github/workflows/publish-next.yml b/.github/workflows/publish-next.yml new file mode 100644 index 0000000..fb92162 --- /dev/null +++ b/.github/workflows/publish-next.yml @@ -0,0 +1,56 @@ +name: Publish (next) + +# Publishes a "next" snapshot of vscode-messenger-common, vscode-messenger and +# vscode-messenger-webview to npm under the `next` dist-tag. +# +# Manually triggered only. Uses npm trusted publishing (OIDC) + staged publishing: +# the workflow stages the packages on npm without requiring a token, a maintainer +# must then explicitly approve (or reject) the staged version with 2FA on +# npmjs.com before it goes live. +# +# The vscode-messenger-devtools extension is not part of this workflow. + +on: + workflow_dispatch: {} + +permissions: + id-token: write # Required for npm OIDC trusted publishing + contents: read + +jobs: + publish-next: + name: Stage npm next snapshot + runs-on: ubuntu-latest + environment: publish + timeout-minutes: 20 + steps: + - name: Checkout + uses: actions/checkout@v4 + + - name: Use Node.js + uses: actions/setup-node@v4 + with: + node-version: '22' + registry-url: 'https://registry.npmjs.org' + + # Staged publishing requires npm CLI >= 11.15.0 + - name: Update npm + run: npm install -g npm@latest + + - name: Install dependencies + run: npm ci + + - name: Build + run: npm run build + + - name: Test + run: npm test + + - name: Prepare next version + run: npm run prepare-next + + - name: Stage publish + run: | + npm stage publish -w packages/vscode-messenger-common --tag next --access public + npm stage publish -w packages/vscode-messenger --tag next --access public + npm stage publish -w packages/vscode-messenger-webview --tag next --access public diff --git a/.github/workflows/publish.yml b/.github/workflows/publish.yml new file mode 100644 index 0000000..ae4da2b --- /dev/null +++ b/.github/workflows/publish.yml @@ -0,0 +1,56 @@ +name: Publish + +# Publishes vscode-messenger-common, vscode-messenger and vscode-messenger-webview to npm. +# Triggered by pushing a semver tag (e.g. v0.7.0, v0.7.0-next.). +# +# Uses npm trusted publishing (OIDC) + staged publishing: the workflow stages the +# packages on npm without requiring a token, a maintainer must then explicitly +# approve (or reject) the staged version with 2FA on npmjs.com before it goes live. +# +# The vscode-messenger-devtools extension (VS Marketplace / Open VSX) is published +# separately and is not part of this workflow. + +on: + push: + tags: + - 'v*.*.*' + workflow_dispatch: {} + +permissions: + id-token: write # Required for npm OIDC trusted publishing + contents: read + +jobs: + publish: + name: Stage npm packages + runs-on: ubuntu-latest + environment: publish + timeout-minutes: 20 + steps: + - name: Checkout + uses: actions/checkout@v4 + + - name: Use Node.js + uses: actions/setup-node@v4 + with: + node-version: '22' + registry-url: 'https://registry.npmjs.org' + + # Staged publishing requires npm CLI >= 11.15.0 + - name: Update npm + run: npm install -g npm@latest + + - name: Install dependencies + run: npm ci + + - name: Build + run: npm run build + + - name: Test + run: npm test + + - name: Stage publish + run: | + npm stage publish -w packages/vscode-messenger-common --access public + npm stage publish -w packages/vscode-messenger --access public + npm stage publish -w packages/vscode-messenger-webview --access public diff --git a/AGENTS.md b/AGENTS.md index 55af622..61af25d 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -35,7 +35,7 @@ See [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) for the full module index. - Never hand-edit `packages/*/lib/` or `packages/*/webview-ui/build/` — these are build outputs regenerated by `npm run build`. - Never hand-edit `examples/*/media/web-view-bundle-*.js` — generated by the `browserify` step of `npm run build`. -- The three publishable packages (`vscode-messenger`, `vscode-messenger-webview`, `vscode-messenger-common`) must keep matching version ranges on each other — see [releasing.md](releasing.md) before touching any `package.json` version or dependency range. +- The three publishable packages (`vscode-messenger`, `vscode-messenger-webview`, `vscode-messenger-common`) must keep matching version ranges on each other — see [RELEASING.md](RELEASING.md) before touching any `package.json` version or dependency range. - Done means `npm run build`, `npm test`, and `npm run lint` all pass locally; include the final line(s) of each command's output in your response to confirm. - A change to a package's public API includes an updated usage example in [README.md](README.md) in the same change — the README is this library's primary consumer-facing contract. - For non-publishable packages (devtools, examples), update the relevant section of [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) instead of README.md when their public API changes. @@ -48,5 +48,5 @@ See [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) for the full module index. ## Pointers - [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) — package layering and module index. -- [releasing.md](releasing.md) — npm, Open VSX, and VS Code Marketplace release steps. +- [RELEASING.md](RELEASING.md) — npm, Open VSX, and VS Code Marketplace release steps. - [.github/skills/vscode-messenger/SKILL.md](.github/skills/vscode-messenger/SKILL.md) — consumer-facing skill for downstream users of this library (message-type patterns, cancellation, devtools wiring). diff --git a/RELEASING.md b/RELEASING.md new file mode 100644 index 0000000..1409d91 --- /dev/null +++ b/RELEASING.md @@ -0,0 +1,171 @@ +# Releasing + +## Release NPM packages + +Packages are: + +- vscode-messenger-common (shared) +- vscode-messenger (vscode API) +- vscode-messenger-webview (webview API) + +### Reviewing staged packages + +Applies to both the `next` and `latest` flows below whenever a package is staged (via CI or `npm stage publish` locally). Before approving: + +1. List staged versions to get the stage-id: + + ```bash + npm stage list vscode-messenger-common + npm stage list vscode-messenger + npm stage list vscode-messenger-webview + ``` + +2. View metadata (version, dist-tag, size, file list) without downloading: + + ```bash + npm stage view + ``` + +3. Download and inspect the actual tarball contents — catches things the metadata view won't, like stale build output, an unintended `files` whitelist, or leaked secrets: + + ```bash + npm stage download + tar -tzf .tgz # list contents + tar -xzf .tgz -C /tmp/review && cd /tmp/review/package + ``` + + Check: correct `version`/`main`/`types` in `package.json`, only `lib`/`src` present (no `tests`, `node_modules`, `.map` files if unwanted), and that `lib/*.js` actually reflects the intended commit. + +4. Approve or reject (2FA required either way): + + ```bash + npm stage approve + # or + npm stage reject + ``` + +The npmjs.com "Staged Packages" tab covers steps 1–2 visually but can't show tarball contents — for anything beyond a routine release, do the CLI download+extract check too. + +### Release next version + +Can be done via CI, or manually from your machine. Either way it publishes under the `next` dist-tag and doesn't touch the committed package.json versions. + +#### Via CI workflow (next) + +Trigger the [Publish (next) workflow](.github/workflows/publish-next.yml) manually (Actions → "Publish (next)" → Run workflow). It uses npm trusted publishing (OIDC) combined with [staged publishing](https://docs.npmjs.com/staged-publishing) — see [Reviewing staged packages](#reviewing-staged-packages) above, then approve to make it live. + +#### Manual local publish (next) + +Install dependencies and build the project: + +```bash +npm install +npm run build +``` + +Update versions to add `-next.` suffix (writes to the 3 packages' package.json on disk, no git tag/commit — discard these changes afterwards, e.g. `git checkout -- packages/*/package.json`): + +```bash +npm run prepare-next +``` + +Publish this version with tag `next`. This uses your own npm login/2FA, not OIDC: + +```bash +npm run publish-next +``` + +### Release new version + +Can be done via CI, or manually from your machine. + +Either way, first bump versions: + +1. Manually change versions and dependency versions. This includes package.json files in all three NPM packages (see the list above) — they must keep matching version ranges on each other. +2. Commit the version bump to `main`. + +The `vscode-messenger-devtools` extension is published separately (see below), not by either of these. + +#### Via CI workflow (release) + +The [Publish workflow](.github/workflows/publish.yml) is triggered by pushing a semver tag (`vX.Y.Z`) on `main`. It uses npm trusted publishing (OIDC, no token) combined with [staged publishing](https://docs.npmjs.com/staged-publishing): the workflow only stages the packages, a maintainer must approve (or reject) the staged version on [npmjs.com](https://www.npmjs.com/) (or via `npm stage approve `) with 2FA before it becomes publicly available. + +1. Tag the commit and push: + + ```bash + git tag vX.Y.Z + git push origin vX.Y.Z + ``` + +2. Wait for the workflow to stage all three packages, then review and approve each (see [Reviewing staged packages](#reviewing-staged-packages) above). + +#### Manual local publish (release) + +Install dependencies and build the project: + +```bash +npm install +npm run build +``` + +Publish this version with tag `latest`. This uses your own npm login/2FA, not OIDC: + +```bash +npm run publish-latest +``` + +To also get a review step locally, stage instead of publishing directly and approve from npmjs.com afterwards: + +```bash +npm stage publish --workspaces --access public --tag latest +``` + +#### Mistakes / re-tagging + +- If a staged version has **not** been approved yet, reject it first (`npm stage reject `, needs 2FA) — this frees up the version number. Then delete and re-push the tag on the fixed commit: + + ```bash + git tag -d vX.Y.Z + git push origin :refs/tags/vX.Y.Z + git tag vX.Y.Z + git push origin vX.Y.Z + ``` + +- If a version was already **approved and published**, it is immutable — npm will never let you re-publish the same version number again. Bump to a new version instead. + +## Devtools extension + +Extension package is `vscode-messenger-devtools`. + +### Devtools extension build + +- Add a changelog.md entry +- Install vsce `npm install -g @vscode/vsce` is not already installed + +```bash +cd ../vscode-messenger-devtools +vsce package --no-dependencies +``` + +- `vsce package` will also run `npm run vscode:prepublish` + +#### Publish Open VSX + +- Check the changelog.md entry + +- Create token `https://open-vsx.org/user-settings/tokens` or use existing + +- Publish OpenVSX `npx ovsx publish --no-dependencies`. You will be prompted to enter the token. + +#### Publish VSCode + +- Install vsce `npm install -g @vscode/vsce` is not already installed + +- Create token in `https://dev.azure.com/typefox/_usersSettings/tokens` + - click Show all scopes link below the Scopes section in the Scopes list, scroll to Marketplace and select Manage scope + - click Create token + - copy the token + +- Login `vsce login typefox` + +- Publish: `vsce publish --no-dependencies` diff --git a/releasing.md b/releasing.md deleted file mode 100644 index b89b1ca..0000000 --- a/releasing.md +++ /dev/null @@ -1,84 +0,0 @@ -# Releasing - -## Release NPM packages - -Packages are: - -- vscode-messenger-common (shared) -- vscode-messenger (vscode API) -- vscode-messenger-webview (webview API) - -### Release next version - -Install dependencies and build the project: - -```bash -npm install -npm run build -``` - -Update versions to add `-next.` suffix. - -```bash -npm run prepare-next -``` - -Publish this version with tag `next`. - -```bash -npm run publish-next -``` - -### Release new version - -Install dependencies and build the project: - -```bash -npm install -npm run build -``` - -Manually change versions and dependency versions. This includes package.json files in the NPM packages. See the list above. - -Publish this version with tag `latest`. - -```bash -npm run publish-latest -``` - -## Devtools extension - -Extension package is `vscode-messenger-devtools`. - -### Devtools extension build - -- Add a changelog.md entry -- Install vsce `npm install -g @vscode/vsce` is not already installed - -```bash -cd ../vscode-messenger-devtools -vsce package --no-dependencies -``` - -- `vsce package` will also run `npm run vscode:prepublish` - -#### Publish Open VSX - -- Check the changelog.md entry - -- Create token `https://open-vsx.org/user-settings/tokens` or use existing - -- Publish OpenVSX `npx ovsx publish --no-dependencies`. You will be prompted to enter the token. - -#### Publish VSCode - -- Install vsce `npm install -g @vscode/vsce` is not already installed - -- Create token in `https://dev.azure.com/typefox/_usersSettings/tokens` - - click Show all scopes link below the Scopes section in the Scopes list, scroll to Marketplace and select Manage scope - - click Create token - - copy the token - -- Login `vsce login typefox` - -- Publish: `vsce publish --no-dependencies`