ianmacartney · Nov 11, 2026 · Nov 11, 2026 · Nov 11, 2026 · Nov 11, 2026
diff --git a/.changeset/README.md b/.changeset/README.md
@@ -0,0 +1,4 @@
+# Release notes
+
+See [CONTRIBUTING.md](../CONTRIBUTING.md#releases) for contributing release
+notes and preparing a release.
diff --git a/.changeset/config.json b/.changeset/config.json
@@ -0,0 +1,11 @@
+{
+  "$schema": "https://unpkg.com/@changesets/config@4.0.1/schema.json",
+  "baseBranch": "main",
+  "access": "public",
+  "changelog": "@changesets/cli/changelog",
+  "commit": false,
+  "fixed": [],
+  "linked": [],
+  "updateInternalDependencies": "patch",
+  "ignore": []
+}
diff --git a/.github/workflows/lint-workflows.yml b/.github/workflows/lint-workflows.yml
@@ -0,0 +1,43 @@
+name: Lint workflows
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.head_ref || github.run_id }}
+  cancel-in-progress: true
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - ".github/workflows/**"
+      - ".github/actions/**"
+  pull_request:
+    branches: ["**"]
+    paths:
+      - ".github/workflows/**"
+      - ".github/actions/**"
+
+permissions:
+  contents: read
+
+jobs:
+  actionlint:
+    name: actionlint
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
+        with:
+          persist-credentials: false
+      - uses: kjanat/actionlint@08bb2c4f0d039744455b87aef1c647fb8b66d37b # v1.17.0
+
+  zizmor:
+    name: zizmor
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    permissions:
+      security-events: write
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
+        with:
+          persist-credentials: false
+      - uses: zizmorcore/zizmor-action@53290badfa369cb0bf7ad16342cb62c2fa47ac7b # v0.8.0
diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml
@@ -0,0 +1,222 @@
+name: Release
+
+on:
+  push:
+    branches: [main]
+  workflow_dispatch:
+    inputs:
+      commit:
+        description:
+          "Optional 40-character version-bump commit SHA reachable from the
+          selected ref"
+        required: false
+        type: string
+
+concurrency:
+  group: ${{ github.workflow }}
+  queue: max
+  cancel-in-progress: false
+
+permissions: {}
+
+env:
+  NODE_VERSION: "24.22.1"
+
+jobs:
+  plan:
+    if: github.repository_owner == 'convex'
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    permissions:
+      contents: read
+    outputs:
+      sha: ${{ steps.select.outputs.sha }}
+      name: ${{ steps.select.outputs.name }}
+      version: ${{ steps.select.outputs.version }}
+      channel: ${{ steps.select.outputs.channel }}
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
+        with:
+          fetch-depth: 0
+          persist-credentials: false
+      - uses: actions/setup-node@949feb2413d6458794dcd2491c4babbbce0c15c1 # v7.1.0
+        with:
+          node-version: ${{ env.NODE_VERSION }}
+          package-manager-cache: false
+      - id: select
+        name: Select the latest version-bump commit
+        env:
+          RELEASE_COMMIT: ${{ inputs.commit }}
+        run: |
+          if [[ "$GITHUB_EVENT_NAME" == workflow_dispatch ]]; then
+            source="${RELEASE_COMMIT:-$GITHUB_SHA}"
+            [[ "$source" =~ ^[0-9a-f]{40}$ ]] || { echo 'Expected a 40-character commit SHA' >&2; exit 1; }
+            git merge-base --is-ancestor "$source" "$GITHUB_SHA"
+          else
+            before=$(jq -r .before "$GITHUB_EVENT_PATH")
+            source=''
+            candidates=$(git rev-list --first-parent "$before..$GITHUB_SHA" -- package.json)
+            while read -r candidate && [[ -n "$candidate" ]]; do
+              current=$(git show "$candidate:package.json" | jq -r .version)
+              previous=$(git show "$candidate^1:package.json" | jq -r .version)
+              if [[ "$current" != "$previous" ]]; then source="$candidate"; break; fi
+            done <<< "$candidates"
+            if [[ -z "$source" ]]; then echo 'No version bump'; exit 0; fi
+          fi
+          name=$(git show "$source:package.json" | jq -r .name)
+          VERSION=$(git show "$source:package.json" | jq -r .version)
+          PREVIOUS_VERSION=$(git show "$source^1:package.json" | jq -r .version)
+          export VERSION PREVIOUS_VERSION
+          node --input-type=module <<'NODE'
+          import { execFileSync } from 'node:child_process';
+          import { appendFileSync } from 'node:fs';
+          import { createRequire } from 'node:module';
+          // Use the standard SemVer library bundled with the pinned npm.
+          const npmRoot = execFileSync('npm', ['root', '-g'], { encoding: 'utf8' }).trim();
+          const semver = createRequire(`${npmRoot}/npm/package.json`)('semver');
+          const { VERSION: version, PREVIOUS_VERSION: previous, GITHUB_REF: ref } = process.env;
+          if (semver.valid(version) !== version || !semver.gt(version, previous)) throw new Error('Selected commit must increase the package version');
+          const pre = semver.prerelease(version);
+          const channel = pre ? String(pre[0]) : 'latest';
+          if (pre && (!/^[a-z][a-z0-9-]*$/.test(channel) || channel === 'latest' || semver.validRange(channel))) throw new Error('Invalid prerelease channel');
+          if (!pre && ref !== 'refs/heads/main') throw new Error('Stable releases require main');
+          appendFileSync(process.env.GITHUB_OUTPUT, `channel=${channel}\n`);
+          NODE
+          tag="v$VERSION"
+          if git show-ref --verify --quiet "refs/tags/$tag"; then
+            [[ "$(git rev-parse "$tag^{commit}")" == "$source" ]] || { echo "$tag points elsewhere" >&2; exit 1; }
+            if [[ "$GITHUB_EVENT_NAME" != workflow_dispatch ]]; then
+              echo "$tag was already staged; skipping automatic release"
+              exit 0
+            fi
+          fi
+          {
+            echo "sha=$source"
+            echo "name=$name"
+            echo "version=$VERSION"
+          } >> "$GITHUB_OUTPUT"
+
+  build:
+    needs: plan
+    if: needs.plan.outputs.sha != ''
+    runs-on: ubuntu-latest
+    timeout-minutes: 30
+    permissions:
+      contents: read
+    outputs:
+      artifact_id: ${{ steps.upload.outputs.artifact-id }}
+      sha256: ${{ steps.digest.outputs.sha256 }}
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
+        with:
+          ref: ${{ needs.plan.outputs.sha }}
+          persist-credentials: false
+      - uses: actions/setup-node@949feb2413d6458794dcd2491c4babbbce0c15c1 # v7.1.0
+        with:
+          node-version: ${{ env.NODE_VERSION }}
+          package-manager-cache: false
+      - run: npm ci
+      - name: Validate release notes
+        run: |
+          # Compare against this checkout while reading all notes, including prerelease state.
+          git update-ref refs/heads/main HEAD
+          npx changeset status --output "$RUNNER_TEMP/changesets.json"
+          jq -e '.changesets | length == 0' "$RUNNER_TEMP/changesets.json"
+          version=$(jq -r .version package.json)
+          awk -v version="$version" '/^## / { active=($0 == "## " version); next } active && !/^#/ && /[[:alnum:]]/ { found=1 } END { exit !found }' CHANGELOG.md
+      - run: npm run build
+      - run: npm run check
+      - name: Run E2E tests and verify generated code
+        env:
+          CONVEX_AGENT_MODE: anonymous
+          CONVEX_DISABLE_TELEMETRY: "1"
+        run: |
+          npm run test:e2e
+          git diff --exit-code -- src/component/_generated example/convex/_generated
+          test -z "$(git ls-files --others --exclude-standard src/component/_generated example/convex/_generated)"
+      - name: Pack the tested package
+        run: |
+          mkdir -p "$RUNNER_TEMP/npm-release"
+          npm pack --ignore-scripts --pack-destination "$RUNNER_TEMP/npm-release"
+      - id: digest
+        run:
+          echo "sha256=$(sha256sum "$RUNNER_TEMP"/npm-release/*.tgz | cut -d ' '
+          -f 1)" >> "$GITHUB_OUTPUT"
+      - id: upload
+        uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7
+        with:
+          name: npm-release-${{ needs.plan.outputs.sha }}
+          path: ${{ runner.temp }}/npm-release/*.tgz
+          if-no-files-found: error
+
+  stage:
+    needs: [plan, build]
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    permissions:
+      contents: read
+      id-token: write
+    steps:
+      - uses: actions/setup-node@949feb2413d6458794dcd2491c4babbbce0c15c1 # v7.1.0
+        with:
+          node-version: ${{ env.NODE_VERSION }}
+          package-manager-cache: false
+      - uses: actions/download-artifact@9000827ccba6bdab643e8b6fd33ac0654aef8333 # v8
+        with:
+          artifact-ids: ${{ needs.build.outputs.artifact_id }}
+          path: ${{ runner.temp }}/npm-release
+          merge-multiple: true
+      - name: Stage the tested artifact
+        env:
+          SOURCE_SHA: ${{ needs.plan.outputs.sha }}
+          PACKAGE_NAME: ${{ needs.plan.outputs.name }}
+          VERSION: ${{ needs.plan.outputs.version }}
+          CHANNEL: ${{ needs.plan.outputs.channel }}
+          EXPECTED_SHA256: ${{ needs.build.outputs.sha256 }}
+        run: |
+          set -o pipefail
+          set -- "$RUNNER_TEMP"/npm-release/*.tgz
+          test "$#" -eq 1
+          TARBALL="$1"
+          echo "$EXPECTED_SHA256  $TARBALL" | sha256sum -c -
+          {
+            echo "$PACKAGE_NAME@$VERSION — source $SOURCE_SHA — npm channel $CHANNEL"
+            echo "Review on npm's Staged Packages page, then approve with 2FA or npm stage approve <stage-id>."
+          } >> "$GITHUB_STEP_SUMMARY"
+          # npm reads GITHUB_SHA for provenance; checkout alone does not change it.
+          GITHUB_SHA="$SOURCE_SHA" npm stage publish "$TARBALL" \
+            --ignore-scripts --provenance --access public --tag "$CHANNEL" \
+            2>&1 | tee "$RUNNER_TEMP/npm-stage.log"
+      - name: Preserve staging output and stage ID
+        if: always()
+        run: |
+          if test -f "$RUNNER_TEMP/npm-stage.log"; then
+            cat "$RUNNER_TEMP/npm-stage.log" >> "$GITHUB_STEP_SUMMARY"
+          fi
+
+  tag:
+    needs: [plan, stage]
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
+        with:
+          ref: ${{ needs.plan.outputs.sha }}
+          fetch-depth: 0
+          persist-credentials: false
+      - name: Tag the staged source
+        env:
+          GH_TOKEN: ${{ github.token }}
+          SOURCE_SHA: ${{ needs.plan.outputs.sha }}
+          VERSION: ${{ needs.plan.outputs.version }}
+        run: |
+          tag="v$VERSION"
+          if git show-ref --verify --quiet "refs/tags/$tag"; then
+            test "$(git rev-parse "$tag^{commit}")" = "$SOURCE_SHA"
+          else
+            git tag "$tag" "$SOURCE_SHA"
+            gh auth setup-git
+            git push origin "refs/tags/$tag"
+          fi
diff --git a/.github/workflows/test.yml b/.github/workflows/test.yml
@@ -4,35 +4,48 @@ concurrency:
   cancel-in-progress: true
 
 on:
+  workflow_dispatch:
   push:
     branches: [main]
   pull_request:
     branches: ["**"]
 
+permissions: {}
+
 jobs:
   check:
     name: Test and lint
     runs-on: ubuntu-latest
     timeout-minutes: 30
+    permissions:
+      contents: read
 
     steps:
-      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          fetch-depth: 0
+          persist-credentials: false
 
       - name: Node setup
-        uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e # v6
+        uses: actions/setup-node@949feb2413d6458794dcd2491c4babbbce0c15c1 # v7.1.0
         with:
           cache-dependency-path: package.json
-          node-version: "24.x"
+          node-version: "24.22.1"
           cache: "npm"
 
       - name: Install and build
         run: |
-          npm i
+          npm ci
           npm run build
-      - name: Publish package for testing branch
-        run: npx pkg-pr-new publish || echo "pkg-pr-new failed"
       - name: Test
+        run: npm run check
+      - name: Run E2E smoke test and verify generated code
+        env:
+          CONVEX_AGENT_MODE: anonymous
+          CONVEX_DISABLE_TELEMETRY: "1"
         run: |
-          npm run test
-          npm run typecheck
-          npm run lint
+          npm run test:e2e
+          git diff --exit-code -- src/component/_generated example/convex/_generated
+          test -z "$(git ls-files --others --exclude-standard src/component/_generated example/convex/_generated)"
+      - name: Publish package for testing branch
+        run: npx pkg-pr-new publish || echo "pkg-pr-new failed"