From dfa41046b6210b59f66cae1f83042c123e5efad6 Mon Sep 17 00:00:00 2001
From: Andrey <zertsalov2910@gmail.com>
Date: Tue, 14 Jul 2026 14:31:39 +0100
Subject: [PATCH] ci: publish prerelease builds to npm under the `next`
 dist-tag

Every push to main (except release-please's release commits) now publishes
a prerelease version like 1.5.1-next.<timestamp>.g<sha> with `npm publish
--tag next`, so teammates can QA merged-but-unreleased work via
`npx zerion-cli@next` while regular users keep getting `latest`.
Also supports manual workflow_dispatch from any branch.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 .github/workflows/publish-next.yml | 43 ++++++++++++++++++++++++++++++
 README.md                          | 27 +++++++++++++++++++
 2 files changed, 70 insertions(+)
 create mode 100644 .github/workflows/publish-next.yml

diff --git a/.github/workflows/publish-next.yml b/.github/workflows/publish-next.yml
new file mode 100644
index 0000000..8ef5f42
--- /dev/null
+++ b/.github/workflows/publish-next.yml
@@ -0,0 +1,43 @@
+name: Publish next
+
+on:
+  push:
+    branches: [main]
+  # Allows publishing a prerelease from any branch via the Actions UI
+  workflow_dispatch: {}
+
+# Serialize runs so a slow older build can't move the `next` tag past a newer one
+concurrency:
+  group: publish-next
+  cancel-in-progress: false
+
+jobs:
+  publish-next:
+    # Skip release-please's own release commits — those publish `latest` via release-please.yml
+    if: ${{ !startsWith(github.event.head_commit.message, 'chore(main): release') }}
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      id-token: write
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 24
+          registry-url: https://registry.npmjs.org
+
+      - run: npm ci
+
+      - run: npm test
+
+      - name: Set prerelease version
+        # Bump patch so the prerelease sorts above the current stable release,
+        # e.g. 1.5.0 -> 1.5.1-next.20260714093000.g325093a
+        run: |
+          BASE=$(node -p "const v = require('./package.json').version.split('.'); v[2] = Number(v[2]) + 1; v.join('.')")
+          npm version --no-git-tag-version "${BASE}-next.$(date -u +%Y%m%d%H%M%S).g${GITHUB_SHA::7}"
+
+      - run: npm publish --provenance --tag next
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
diff --git a/README.md b/README.md
index ef317b5..ea7b2dd 100644
--- a/README.md
+++ b/README.md
@@ -442,6 +442,33 @@ To force a specific version, add `Release-As: 2.0.0` in a commit message body.
 - `.release-please-manifest.json` tracks the current version
 - `.github/workflows/release-please.yml` handles release PR creation and npm publish
 - `.github/workflows/test.yml` runs tests on PRs and pushes to main
+- `.github/workflows/publish-next.yml` publishes prereleases to the `next` dist-tag (see below)
+
+### Prerelease channel (`@next`)
+
+Every push to `main` (except release commits) publishes a prerelease to npm under the `next` dist-tag, e.g. `1.5.1-next.20260714093000.g325093a`. Regular users are unaffected: `npm install zerion-cli` keeps resolving the `latest` tag, which only moves when a release-please release PR is merged.
+
+To try the latest merged-but-unreleased work:
+
+```bash
+npx zerion-cli@next --help
+# or
+npm install -g zerion-cli@next
+```
+
+To test an unmerged branch, install straight from git — no publish needed:
+
+```bash
+npm install -g github:zeriontech/zerion-ai#<branch>
+```
+
+A prerelease can also be published from any branch manually via the **Publish next** workflow in the Actions tab (`workflow_dispatch`).
+
+If a `next` build turns out broken, point the tag back at a known-good version:
+
+```bash
+npm dist-tag add zerion-cli@<version> next
+```
 
 ## Resources