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.
Schema patches follow the tag
The D1 schema shares that version. A schema change ships as db/patches/<release>.sql, named after
the tag it ships in, so a database stamped 0.6.0 was always upgraded by v0.6.0. Before you name
a new patch, work out the number release-please will pick: before 1.0, feat: and fix: bump the
patch (0.6.0 → 0.6.1) and a breaking change bumps the minor. If the release needs a different
number, force it with a Release-As: x.y.z commit footer rather than naming the patch after a
version it won't ship in. The full procedure is in
db/README.md.
scripts/check-schema-version.mjs enforces this twice:
- On every PR (
ci.yml). Each patch stamps its own version,schema.sqlmatches the newest patch, and no patch that has already been released has changed. - On the release merge (
release-please.yml,--release). Theschema-versionjob runs ahead ofrelease-pleaseand fails if the newest patch is ahead of the release being cut, or if any patch added or edited since the previous tag carries a different number than this release. In that case no tag is created until aRelease-As:footer fixes the number. CI never runs on the release PR itself (it's opened with the defaultGITHUB_TOKEN), so this is the only check it gets.
Dependency updates
Dependabot (.github/dependabot.yml) opens weekly update PRs for npm (the root lockfile covers
every workspace), GitHub Actions, the argon-hasher Cargo crate and the Terraform providers.
Minor and patch bumps are grouped into one PR per ecosystem; majors arrive individually. They commit
as chore(deps): …, so merging one shows up in the changelog without cutting a release on its own.
Some majors are held back on purpose with an ignore rule in dependabot.yml:
- TypeScript stays on 5.x for as long as 5.x is supported. Minor and patch releases still come through the grouped PR.
next-auth v5 ships only as a prerelease (5.0.0-beta.*). Because we are already on a beta,
Dependabot may propose a newer one, but it has not done so reliably (beta.30 → beta.32 never got a
PR). Check npm audit --omit=dev after each release-please cycle, and when it reports a
next-auth / @auth/core advisory that no open Dependabot PR covers, bump the beta by hand.
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.