diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml index 2f89a407..9aebe516 100644 --- a/.github/workflows/release.yml +++ b/.github/workflows/release.yml @@ -396,7 +396,10 @@ jobs: # publisher only to a package that already exists (npm/cli#8544), and staged # publishing cannot create one either. A new package needs one first publish # by hand (with 2FA) or with a temporary token, then a trusted publisher, - # before it joins these steps (docs/release-checklist.md). + # before it joins these steps (docs/release-checklist.md). npm expires an + # unvalidated trusted publisher 48 hours after creation, and only a publish + # from this workflow validates it, so the configuration is a release-day + # step: create it within 48 hours before the tag, not weeks ahead. # # CodeLLDB platform packages (issue #383) go first so the CLI's # optionalDependencies always resolve. They are versioned by the CodeLLDB diff --git a/docs/release-checklist.md b/docs/release-checklist.md index 0e15c4a4..aad7f7c7 100644 --- a/docs/release-checklist.md +++ b/docs/release-checklist.md @@ -20,8 +20,8 @@ Pre-release validation for mcp-debugger. Run `npm run release:dry-run` to automa ### Manual - [ ] **Changelog fragments collated** — run `pnpm changelog:collate` **first**. It folds every `changelog.d/*.md` into `[Unreleased]`, creating category headings in Keep a Changelog order, and deletes the fragments. `pnpm run release:dry-run` fails if any fragment is left uncollated (#546) - [ ] **CHANGELOG reconciled against git history** — run `git log --oneline v..HEAD --no-merges` and confirm every user-visible merge appears under `[Unreleased]` (dependency bumps and pure test/CI-internal changes may be omitted deliberately), and that the section has no duplicate `### Fixed`/`### Added` headers. Since #546 the CI gate requires a fragment on every user-visible PR, so this is now a verification rather than a catch-up — but entries merged **before** #546 are not covered by the gate (#462) -- [ ] **npm trusted publishing configured** — every published `@debugmcp/*` package (the 10 repo-versioned packages and the 5 `codelldb-` packages) must have a trusted publisher at npmjs.com → package Settings → Trusted Publisher (GitHub Actions; org/user: `debugmcp`, repo: `mcp-debugger`, workflow: `release.yml`, environment: blank). These packages publish token-free via OIDC; a publish without this config fails (404/permission error) — configure, then re-run via workflow_dispatch. -- [ ] **First-time packages** — `release.yml` has no token path: npm attaches a trusted publisher only to a package that already exists (npm/cli#8544), and staged publishing cannot create one either. Before tagging a release that introduces a new package, publish its first version once by hand with 2FA (`npm publish --access public` from a Linux or macOS checkout, so executable bits survive), or with a short-lived granular token in a one-off workflow, then configure its trusted publisher. After that, the release publishes it like every other package. +- [ ] **npm trusted publishing configured** — every published `@debugmcp/*` package (the 10 repo-versioned packages and the 5 `codelldb-` packages) must have a trusted publisher at npmjs.com → package Settings → Trusted Publisher (GitHub Actions; org/user: `debugmcp`, repo: `mcp-debugger`, workflow: `release.yml`, environment: blank). These packages publish token-free via OIDC; a publish without this config fails (404/permission error) — configure, then re-run via workflow_dispatch. **A newly created configuration expires 48 hours after creation unless a publish validates it** (npm, since 2026-10-02): it stays listed but can no longer authorize or be edited, and the only fix is to delete it and create a new one, which starts a fresh 48-hour window. Create or recreate a configuration within 48 hours **before** the tag push, never weeks ahead. +- [ ] **First-time packages** — `release.yml` has no token path: npm attaches a trusted publisher only to a package that already exists (npm/cli#8544), and staged publishing cannot create one either. Before tagging a release that introduces a new package, publish its first version once by hand with 2FA (`npm publish --access public` from a Linux or macOS checkout, so executable bits survive), or with a short-lived granular token in a one-off workflow. The hand publish can happen any time; the trusted publisher cannot: because an unvalidated configuration expires after 48 hours, create it within 48 hours before the tag push, as a step of release day. Only a real tag validates it — `release.yml` takes the CLI version from the tag ref and publishes every package by its `package.json` version, so there is no one-package dispatch. After that first OIDC publish, the release publishes it like every other package. - [ ] **Docker Hub credentials** — `DOCKER_USERNAME` and `DOCKER_PASSWORD` secrets are current - [ ] **PyPI trusted publishing configured** — `debug-mcp-server-launcher` has a trusted publisher at pypi.org → project Settings → Publishing (GitHub Actions; owner: `debugmcp`, repo: `mcp-debugger`, workflow: `release.yml`, environment: blank). Publishing is token-free via OIDC with PEP 740 attestations; no `PYPI_TOKEN` secret is needed. - [ ] `release.yml` default ref updated to current tag (for workflow_dispatch reruns) @@ -58,4 +58,4 @@ Pre-release validation for mcp-debugger. Run `npm run release:dry-run` to automa - [ ] Verify the pi package surface: on a machine with pi 0.99+ (a scratch `PI_CODING_AGENT_DIR` keeps your own config untouched), `pi install npm:@debugmcp/mcp-debugger@x.y.z`, then `pi list` shows the package, and `/mcp` in a session shows `mcp-debugger` connected with 29 tools (`mcp__mcp_debugger__*`, deferred) — registered by the package's extension (#841) - [ ] **Website content review** — audit https://debugmcp.io against what this release shipped (language matrix, tool count, feature claims, comparison table) and update `debugmcp/website` - [ ] Update `SECURITY.md` supported-versions table if a new minor line started (should have happened pre-tag) -- [ ] First-publish follow-up: configure trusted publishers for any packages that just had their first release (see Manual section above) +- [ ] First-publish follow-up: for any package whose trusted publisher was created for this release, confirm the configuration validated — `npm view @debugmcp/@x.y.z _npmUser` shows `GitHub Actions (trustedPublisher)`. A hand-published first version does not validate it; if the run skipped the package, the configuration expires 48 hours after creation and must be recreated before the next tag (see Manual section above)