eetr-auth
Contributing

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:

JobWorkflowResult
deploy-docsdocs.ymlBuilds apps/docs and deploys it to GitHub Pages.
publish-clientpublish-client.ymlTests, 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.sql matches the newest patch, and no patch that has already been released has changed.
  • On the release merge (release-please.yml, --release). The schema-version job runs ahead of release-please and 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 a Release-As: footer fixes the number. CI never runs on the release PR itself (it's opened with the default GITHUB_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, not publish-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.

On this page