Releasing
How release-please cuts a release, and what it publishes — the docs site and the npm client.
Releases are cut by release-please. Merging
Conventional Commits into main keeps a release PR up to date; merging that release PR is what
cuts the release. Everything downstream is automatic.
What a release does
.github/workflows/release-please.yml runs on every push to main. When the release PR merges,
release_created is true and two follow-on jobs fire in the same workflow run:
| Job | Workflow | Result |
|---|---|---|
deploy-docs | docs.yml | Builds apps/docs and deploys it to GitHub Pages. |
publish-client | publish-client.yml | Tests, builds, and publishes @eetr/eetr-auth-client to npm. |
Why they live in release-please.yml
Releases created with the default GITHUB_TOKEN do not trigger further workflow runs, so an
on: release trigger would never fire. Both jobs are workflow_call targets invoked from the same
run instead. Both are also workflow_dispatch-able for a manual re-publish.
Versioning
There is one version for the whole monorepo, tracked in .release-please-manifest.json.
release-please-config.json propagates it into apps/auth/package.json,
packages/eetr-auth-client/package.json, and README.md via extra-files — so the npm client's
version always matches the release tag. Never hand-edit those versions.
npm publishing
The client publishes with npm trusted publishing (OIDC): there is no NPM_TOKEN secret. The
publish-client job requests id-token: write (the caller grants it too — both parent and child
need it), upgrades to the latest npm CLI (trusted publishing needs npm ≥ 11.5.1), and runs
npm publish from packages/eetr-auth-client. npm attaches a provenance attestation automatically.
The trusted publisher names release-please.yml, not publish-client.yml
npm validates the OIDC claim against the calling workflow, not the workflow that actually runs
npm publish. Since publish-client.yml is invoked through workflow_call, the publisher
configured on npm must be release-please.yml. Getting this wrong fails with a misleading
404 Not Found - PUT rather than an auth error.
Don't add registry-url to setup-node
registry-url: makes actions/setup-node write an .npmrc containing
//registry.npmjs.org/:_authToken=${NODE_AUTH_TOKEN}. With no token supplied that expands to a
placeholder, and npm attempts classic token auth instead of OIDC — again failing with a 404 on
PUT. Installing public dependencies needs no auth, so the option is deliberately absent.
The job is idempotent: it checks npm view <name>@<version> first and skips publishing if that
version is already on the registry, so a re-run can't fail the release.
To retry a publish that failed, re-run the publish-client job from the original release-please
workflow run — the caller is still release-please.yml, so the OIDC claim still matches. The
workflow_dispatch trigger on publish-client.yml runs the build and tests, but cannot authenticate
against a publisher configured for release-please.yml (npm allows only one publisher per package).
One-time npm setup
On npmjs.com, under the @eetr/eetr-auth-client package → Settings →
Trusted publisher, add a GitHub Actions publisher with:
- Organization or user:
eetr-ai - Repository:
eetr-auth - Workflow filename:
release-please.yml— the caller, notpublish-client.yml - Environment: (leave empty)
The @eetr scope must allow public publishing, and the package's publishConfig.access is already
public. A trusted publisher can only be attached to a package that already exists on the registry —
@eetr/eetr-auth-client was first published manually, so this is already done and every release from
now on publishes automatically.