ci: publish the npm packages from CI by trusted publishing, with provenance

Merged
AL
16h ago
+82-4

Closes #246.

Every package is published by hand with a one-time password today, so none has provenance. This adds a workflow that publishes by npm's trusted publishing. It stores no token, needs no one-time password, and npm records each tarball's provenance: the run and the commit it was built from. The workflow mirrors vscode-publish.yml, which has published the extension to Open VSX this way since 0.1.1.

What changes

  • .github/workflows/publish.yml, run by hand from main in the npm environment, with id-token: write:
    • Setup: Node 24, because pnpm publishes through npm and npm takes a trusted publisher's token from 11.5.1, which Node 22's npm 10 is not. A step fails the run before anything else if npm is older. There is no dependency cache, as in vscode-publish.yml.
    • Publish: pnpm -r --workspace-concurrency=1 publish --access public --no-git-checks. pnpm publishes every package whose version npm lacks, in dependency order and one at a time, and passes over the rest. Each package's prepublishOnly runs first, as on a publish by hand, with Chromium installed for the browser tests.
    • Git checks off: prepack writes files into the tree, and the environment already holds the run to main.
    • NPM_CONFIG_PROVENANCE: true, so a run that cannot record provenance fails instead of publishing without it.
    • A dry-run input packs and checks without publishing. A package that pins another one going out in the same release stops at its own check that the pin is on npm.
  • design/build.md: the publishing section starts with the rule and how the workflow publishes. A publish by hand with a one-time password still works, without provenance.
  • design/commands.md: names gh workflow run publish.yml.

Your part, once, before the first run

  1. The environment: Settings, Environments, a new npm environment whose deployment branches are main only.

  2. The publishers: on npmjs.com, for each of the nine packages, Settings, then Trusted publisher, then GitHub Actions, with:

    • organisation missing-elements;
    • repository h5p-toolkit;
    • workflow publish.yml;
    • environment npm.

    The nine packages: player, runtime, libraries, normalize, verify, embed, cmi5, author, mcp.

  3. Optional, after a release from CI: set each package's publishing access to require two-factor authentication and refuse tokens.

The release flow changes at one step: after the bump is committed and pushed, run the workflow (gh workflow run publish.yml, or from the Actions tab) instead of pnpm publish. Run ci.yml by hand first before a player release, as now.

Tested

  • The workflow file: it parses as YAML, with one job of seven steps.
  • The npm check: it refuses 10.9.2 and 11.5.0 and passes 11.5.1, 11.6.2 and 12.0.0.
  • pnpm 10.24.0's own code: pnpm publish runs npm publish <tarball>, and the recursive publish asks the registry first (isAlreadyPublished) and skips a version npm has.
  • The repository field: all nine packages give git+https://github.com/missing-elements/h5p-toolkit.git, which npm's provenance check compares with the repository the run is in.
  • Not tested: a real publish, which needs the steps above. The next release is its first run. The dry run on the bump commit checks everything up to the upload.

Summary by cubic

Moves package publishing from hand-run pnpm publish (one-time password, no provenance) to a CI workflow that uses npm's trusted publishing: no token is stored, and npm records each tarball's provenance. The next release is the workflow's first real run, so it is deliberately not tested end to end before merge.

Setup, once

  • Create an npm environment in the repository settings whose deployment branches are main only.
  • On npmjs.com, register all nine packages (player, runtime, libraries, normalize, verify, embed, cmi5, author, mcp) as trusted publishers for this repo, the publish.yml workflow, and the npm environment.
  • Releasing now means running gh workflow run publish.yml from main instead of pnpm publish. It publishes every package whose version npm lacks, in dependency order, one at a time; a dry-run input packs and checks without publishing.
  • The workflow runs Node 24 because pnpm publishes through npm, which supports trusted-publisher tokens only from 11.5.1, and sets NPM_CONFIG_PROVENANCE: true so a run that cannot record provenance fails instead of publishing without it.
  • No registry-url is set: the workflow targets npm's default registry, and setup-node would write a placeholder token for it. Each package's prepublishOnly runs first, as on a publish by hand; the player's begins by checking that the pack it names is on npm.