Stage npm releases in CI and tag successful uploads by ianmacartney · Pull Request #1022 · convex/convex-helpers

ianmacartney · 2026-10-09T01:27:25Z

A release should be easy to start locally while still requiring a maintainer's npm 2FA approval before the package becomes public. This PR replaces laptop publishing and tag-triggered publishing with a version-bump commit → CI staging → Git tag flow.

Release flow

Run npm run release from a clean checkout containing current main. It runs checks, prepares the version/changelog/lockfile, commits, and pushes to main without creating a local tag. Direct pushes and release PRs use the same CI path; neither a release-PR bot nor a merge queue is required.
The command prints the commit's CI checks URL and the maintainer's npm Staged Packages URL. --watch follows that commit's Release run and opens the approval page after success when local npm whoami succeeds. Without local npm authentication it still watches CI and prints manual approval instructions. Local npm login only discovers the approval-page username; CI uses trusted publishing.
CI finds the version-bump commit in the push, including a release followed by ordinary commits. Push one release at a time; multiple version bumps in a push fail with a clear error. It checks out the exact release commit, validates/builds/tests it, and uploads it with npm stage publish --provenance. The planner uses npm's semver validator, and staging requires nonempty notes in the current version's changelog section. Stable versions use latest; prerelease identifiers select alpha, beta, etc., with next for identifiers npm treats as version ranges.
A single release.yml runs plan → build/pack → stage → tag, without a matrix or reusable workflow. Installation, build, tests, and packing have no OIDC permission. The staging job downloads that run’s immutable tarball artifact and uploads it with scripts disabled; it does not install dependencies or execute package code. The tag job creates npm/<version> at the source commit after staging succeeds. This job has GitHub write permission but performs no checkout or execution of package code. An existing matching tag is accepted; a conflicting tag is never moved.
A maintainer reviews and approves the staged version on npm with 2FA. That is the final step—there is no polling, delayed-tagging workflow, or follow-up Git operation.

The Git tag records successful staging, not approval or public availability. A rejected candidate can keep its tag. This deliberately avoids coupling Git bookkeeping to a later interactive approval. If we eventually choose direct publishing, the upload command and npm trust permissions change; the commit and tagging flow stays the same.

Why enforce staging in npm?

Changing the workflow command alone would not protect against a rogue push that changes it back. Before enabling this flow, configure the npm trusted publisher for convex/convex-helpers, workflow release.yml, to allow staged publishing only, disable direct publishing, and remove any CI credentials that bypass approval. npm then enforces the human approval boundary even if workflow code changes. GitHub's tag rules must also permit Actions to create npm/* tags.

The workflow uses actions/setup-node with .nvmrc (Node 24.18.0), whose bundled npm 11.16.0 supports staged publishing. No separate npm installation is needed.

The approval page is https://www.npmjs.com/settings/<npm-username>/staged-packages; the staging log also supplies the ID for npm stage approve <stage-id>. There is no redundant npm run approve wrapper.

Retries and boundaries

A failed local push retains the release commit for recovery; do not bump again.
If staging fails, inspect the failure and rerun failed jobs. Manual dispatch accepts a version-bump commit on the selected ref, defaulting to its tip. gh workflow run release.yml --ref my-alpha-branch explicitly stages a branch release; ordinary branch pushes and opening/updating release PRs do not. The repository guard skips forks to avoid missing-trust failures. No GitHub environment is required. npm errors—including duplicate uploads—remain visible.
If tagging fails after staging, rerun failed jobs, preserving the successful staging job. Rerunning the entire workflow would attempt to upload the reserved version again.
If npm accepted an upload but CI lost the response, inspect the staged package before recovering. Approval and rejection happen on npm; existing Git tags are not rewritten.

Stack and validation

#1024 and #1039 are merged. Review/merge #1022 (this PR) → #1031. This PR retains its reviewed local release command and npm/<version> tags. #1031 will replace custom release preparation with standard Changesets commands and simplify the release helpers.

Follow-up review adjustments isolate build/pack from OIDC staging, explain the disabled cache, and allow explicit branch dispatch while keeping automatic releases limited to main. Example codegen remains checked by the existing Test and lint workflow; this release change does not add a separate codegen step.

Validation: 20 isolated release tests pass, including manual branch dispatch, earlier-commit retries, rejection of commits outside the selected ref, automatic-trigger/fork guards, artifact handoff, tag retries/conflicts, and denied tag writes. Build, lint/typechecks, all 4,128 package tests, and packed tarball checks also pass. actionlint and zizmor pass. No package was staged or published during validation.

ianmacartney · 2026-10-09T01:27:39Z

Use Changesets for versioning and release notes #1031
Stage npm releases in CI and tag successful uploads #1022 👈 (View in Graphite)
main

This stack of pull requests is managed by Graphite. Learn more about stacking.

pkg-pr-new · 2026-10-09T01:28:09Z

Open in StackBlitz

npm i https://pkg.pr.new/convex-helpers@1022

commit: 20191c9

cubic-dev-ai

All reported issues were addressed across 7 files

_{Reply with feedback, questions, or to request a fix.

Re-trigger cubic}

ianmacartney · 2026-10-14T22:51:07Z

I may merge #1024 in first, to refactor into a single package.json and doing everything at the root.
I'm also going to stack on a PR that adds changesets, which may land later depending how it looks

cubic-dev-ai

All reported issues were addressed across 11 files

_{Reply with feedback, questions, or to request a fix.

Re-trigger cubic}

cubic-dev-ai

All reported issues were addressed across 9 files (changes from recent commits).

_{Reply with feedback, questions, or to request a fix.

Re-trigger cubic}

Nicolapps

Thanks for doing this!

I wonder whether it could be helpful to use something like the Changesets release PR feature to avoid the local step, but this is a clear improvement over what we had before

Nicolapps · 2026-10-28T18:55:09Z

+          npm ci
+          npm run release:validate
+          npm run build
+          npm run lint


Can you please consider moving this step to a separate job that doesn’t have id-token: write? This job could store the result as an artifact, which itself would be uploaded by the “stage” step. This gives us more resilience if the install/build/lint steps are maliciously changed to execute bad code. With the current implementation they could get an OIDC token

Great suggestion. done in 69533b1

Nicolapps · 2026-10-28T19:14:54Z

+          npm ci
+          npm run release:validate
+          npm run build
+          npm run lint


Should we verify the codegen too?

Which codegen are you referring to? Unlike a component, I don't think it ships any convex _generated code?

You're right, we don't need to worry about generated files here

Nicolapps · 2026-10-28T19:18:00Z

+
+jobs:
+  plan:
+    if: github.repository == 'convex/convex-helpers' && github.ref == 'refs/heads/main'


With this, we won’t allow this release workflow to run from other branches for alphas. Is this intentional?

If it is intentional, something we could do to improve security is to make the stage step run in a separate GitHub environment that is configured to only run on the main branch, and modifying our NPM trust settings to only allow publication from this environment. This avoids attacks where someone modifies the release.yml file to remove this check

…1024) Make the repository root the publishable `convex-helpers` package, with JavaScript and declaration entrypoints in `dist/`. Keep TypeScript sources in `packages/convex-helpers/`; the Convex examples resolve imports through the root package name. - Consolidate dependencies into root devDependencies, maintain exports explicitly (including `.js`-suffixed helper imports), remove export generation and arethetypeswrong, and compile directly into root `dist/`. - Move CHANGELOG to the root and retain symlinks at the old README/CHANGELOG locations. The root README and example UI layout are already on main through #1039. - Update build/watch/pack scripts, preview publishing, frontend hosting instructions, and the backend test harness for the root package. - Adapt the existing `publish.sh` to the root package and lockfile so this PR can land independently of the new CI release flow. Trusted staging and local release orchestration are introduced separately in #1022. Review/merge **#1024 (this PR) → #1022 → #1031**. This PR is based directly on current main. Preserve the current package version (0.1.129) and the separate Convex-example typecheck. Validation: clean install/build, lint/typechecks, all 1,237 package tests. At the stack tip, the example UI production build and package-content checks also pass: 154 packed files, all explicit entrypoints present, and no example UI, release scripts, test files, or nested package.json shipped. No npm release was published.

cubic-dev-ai

All reported issues were addressed across 11 files

_{Reply with feedback, questions, or to request a fix.

Re-trigger cubic}

github-advanced-security Bot found potential problems Oct 9, 2026

View reviewed changes

Comment thread .github/workflows/release.yml Fixed

Comment thread .github/workflows/release.yml Fixed

ianmacartney requested a review from Nicolapps October 10, 2026 01:38

ianmacartney marked this pull request as ready for review October 10, 2026 01:40

cubic-dev-ai Bot reviewed Oct 10, 2026

View reviewed changes

Comment thread package.json Resolved

Comment thread .github/workflows/release.yml Resolved

ianmacartney mentioned this pull request Oct 13, 2026

Publish convex-helpers from the root with compiled dist entrypoints #1024

Merged

This was referenced Oct 15, 2026

Move example frontend and Vite configuration into example-ui #1032

Merged

Use Changesets for versioning and release notes #1031

Open

ianmacartney force-pushed the ian/deploy-tooling branch 2 times, most recently from 205d457 to f07e852 Compare October 21, 2026 23:13

ianmacartney mentioned this pull request Oct 21, 2026

Copy package README to root and move the example UI #1039

Merged

ianmacartney changed the base branch from main to ian/example-ui-layout October 21, 2026 23:13

ianmacartney force-pushed the ian/example-ui-layout branch from 800deac to f08410b Compare October 21, 2026 23:15

ianmacartney force-pushed the ian/deploy-tooling branch 2 times, most recently from 1de5091 to e88519f Compare October 21, 2026 23:25

ianmacartney changed the base branch from ian/example-ui-layout to main October 22, 2026 01:43

ianmacartney force-pushed the ian/deploy-tooling branch from e88519f to ed139f4 Compare October 22, 2026 05:12

github-advanced-security Bot found potential problems Oct 22, 2026

View reviewed changes

Comment thread .github/workflows/release.yml Fixed

ianmacartney changed the title ~~publish from CI via tag-triggered trusted publishing~~ Stage npm releases in CI and tag successful uploads Oct 22, 2026

ianmacartney changed the base branch from main to ian/package.json-bundling-setup October 22, 2026 05:13

ianmacartney force-pushed the ian/deploy-tooling branch from ed139f4 to ed391c3 Compare October 22, 2026 06:02

cubic-dev-ai Bot reviewed Oct 22, 2026

View reviewed changes

Comment thread scripts/release.test.mjs Resolved

Comment thread .github/workflows/release.yml Resolved

Comment thread scripts/validate-release.mjs Resolved

Comment thread CONTRIBUTING.md Resolved

Comment thread scripts/release-plan.mjs Resolved

cubic-dev-ai Bot reviewed Oct 23, 2026

View reviewed changes

Comment thread scripts/tag-release.test.mjs Resolved

Nicolapps approved these changes Oct 28, 2026

View reviewed changes

ianmacartney force-pushed the ian/package.json-bundling-setup branch from 1b4ff70 to 66bdb82 Compare October 30, 2026 00:39

ianmacartney changed the base branch from ian/package.json-bundling-setup to graphite-base/1022 October 30, 2026 03:04

ianmacartney force-pushed the ian/deploy-tooling branch from a4710b6 to 6d48818 Compare October 30, 2026 03:04

ianmacartney force-pushed the graphite-base/1022 branch from 66bdb82 to 3a06fb2 Compare October 30, 2026 03:04

ianmacartney changed the base branch from graphite-base/1022 to main October 30, 2026 03:04

ianmacartney added 6 commits October 29, 2026 20:06

Stage release commits in CI and tag successful uploads

e4ca143

Use the npm bundled with Node for staged publishing

85afee0

Validate release candidates and tag successful stages independently

cd5a8df

Assert release workflow forwards the npm dist-tag

9a9433e

Simplify CI to stage one release per push

ca69811

Isolate release builds and allow explicit branch staging

69533b1

ianmacartney force-pushed the ian/deploy-tooling branch from 6d48818 to 69533b1 Compare October 30, 2026 03:39

changelog

20191c9

cubic-dev-ai Bot reviewed Oct 30, 2026

View reviewed changes

Comment thread eslint.config.mjs Resolved

ianmacartney merged commit 1815d4a into main Oct 30, 2026
8 checks passed

Conversation

ianmacartney commented Oct 9, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Release flow

Why enforce staging in npm?

Retries and boundaries

Stack and validation

Uh oh!

ianmacartney commented Oct 9, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

Uh oh!

pkg-pr-new Bot commented Oct 9, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

cubic-dev-ai Bot left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

ianmacartney commented Oct 14, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

cubic-dev-ai Bot left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

cubic-dev-ai Bot left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Nicolapps left a comment

Choose a reason for hiding this comment

Uh oh!

Nicolapps Oct 28, 2026

Choose a reason for hiding this comment

Uh oh!

ianmacartney Oct 30, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Nicolapps Oct 28, 2026

Choose a reason for hiding this comment

Uh oh!

ianmacartney Oct 30, 2026

Choose a reason for hiding this comment

Uh oh!

Nicolapps Oct 30, 2026

Choose a reason for hiding this comment

Uh oh!

Nicolapps Oct 28, 2026

Choose a reason for hiding this comment

Uh oh!

cubic-dev-ai Bot left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Reviewers

Uh oh!

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

ianmacartney commented Oct 9, 2026 •

edited

Loading

ianmacartney commented Oct 9, 2026 •

edited

Loading

pkg-pr-new Bot commented Oct 9, 2026 •

edited

Loading

cubic-dev-ai Bot left a comment •

edited

Loading

ianmacartney commented Oct 14, 2026 •

edited

Loading

cubic-dev-ai Bot left a comment •

edited

Loading

cubic-dev-ai Bot left a comment •

edited

Loading

cubic-dev-ai Bot left a comment •

edited

Loading