feat: add lockstep alpha release train (#265)

## Summary

This PR turns the preview release process into a lockstep alpha release
train instead of a manifest-based `zitadel-preview` bundle.

A public alpha now has one version across the CLI, public npm packages,
GoReleaser tag, server binary, and Docker image:

```text
0.1.0-alpha.N
```

The tester experience becomes:

```sh
npx @zitadel/cli@alpha doctor
npx @zitadel/cli@alpha start
npx @zitadel/cli@alpha setup --framework next --server local
```

Exact reports can still pin a train:

```sh
npx @zitadel/cli@0.1.0-alpha.N start
```

## What changed against main

- Configures Changesets to keep all public alpha npm packages in one
fixed group.
- Extends `release-npm.yml` so npm publish remains the first step, then
the same workflow creates `v<version>`, runs GoReleaser, and updates one
draft GitHub prerelease titled `ZITADEL Alpha <version>`.
- Configures GoReleaser so prereleases do not move Docker `latest` or
GitHub latest; only stable releases can do that.
- Makes the CLI derive its default local server image from its own alpha
version, with `--image` and `ZITADEL_LOCAL_IMAGE` still taking
precedence.
- Makes generated Next apps pin `@zitadel/sdk-next` to the exact CLI
alpha version.
- Aligns the current public package baseline to `0.1.0-alpha.1` so PR
tarballs and the consumer journey are internally consistent before the
next Version Packages PR advances the train to `0.1.0-alpha.2`.
- Adds release train scripts, local `check -- --only release` coverage,
an ADR, runbook, and CLI/docs updates.

## Why

The previous manifest-first preview flow made the tester path feel too
complex. This keeps the public UX simple and familiar while preserving
the existing tooling split: Changesets owns npm versioning, GoReleaser
owns Go/image artifacts, and the GitHub Release is the single public
alpha release record.

## Validation

- `corepack pnpm nx test @zitadel/cli --
tests/integration/setup-next.test.ts
tests/unit/lib/orca/patchers/rule/next/index.test.ts`
- `corepack pnpm nx test @zitadel/cli --
tests/unit/scripts/check-alpha-release-plan.test.ts
tests/unit/scripts/release-alpha-train.test.ts`
- `corepack pnpm exec oxlint scripts/check-alpha-release-plan.mjs
apps/cli/tests/unit/scripts/check-alpha-release-plan.test.ts`
- `corepack pnpm run check -- --only pack`
- `corepack pnpm run check -- --only release`
- `corepack pnpm run journey -- --keep`
- `git diff --check`

Author: fforootd

.changeset/README.md

@@ -27,6 +27,8 @@ Pick the affected packages, the bump type (patch / minor / major), and write a o
 The repo is currently in changesets **prerelease mode** with the `alpha` tag (see `.changeset/pre.json`). While in this mode:
 
 - `changeset version` cuts versions like `0.1.0-alpha.0`, `0.1.0-alpha.1`, …
+- Public packages are in one fixed group, so an alpha train uses the same
+  version across `@zitadel/cli`, SDKs, components, and generated API packages.
 - `changeset publish` publishes them under the **`alpha`** npm dist-tag, **not** `latest`. So `npm install @zitadel/cli` keeps resolving the last stable release; consumers opt into prereleases with `@zitadel/cli@alpha`.
 - A package that has never had a stable release is published to `latest` on its first publish (changesets behaviour), then to `alpha` thereafter until it has a stable release.
 
@@ -57,7 +59,14 @@ short-lived OIDC credentials, but npm only accepts public provenance
 attestations from public source repositories. Re-enable provenance when
 `zitadel/nextgen` is public.
 
-The Go server binary is **not** managed by changesets — it is released with `goreleaser` through the manual [`release.yml`](../.github/workflows/release.yml) workflow while the repo is pre-release. See [docs/adrs/002-multi-package-release-strategy.md](../docs/adrs/002-multi-package-release-strategy.md).
+Changesets does not build the Go server binary. During alpha, `release-npm.yml`
+uses the lockstep npm version as the release train version, creates `v<version>`,
+and then runs GoReleaser so the server image and binaries publish into the same
+GitHub Release. The manual [`release.yml`](../.github/workflows/release.yml)
+workflow remains a server snapshot/fallback path. See
+[docs/adrs/002-multi-package-release-strategy.md](../docs/adrs/002-multi-package-release-strategy.md)
+and
+[docs/adrs/023-lockstep-alpha-release-train.md](../docs/adrs/023-lockstep-alpha-release-train.md).
 
 ## Licensing reminder
 

.changeset/config.json

@@ -2,7 +2,19 @@
   "$schema": "https://unpkg.com/@changesets/config@latest/schema.json",
   "changelog": ["@changesets/changelog-github", { "repo": "zitadel/nextgen" }],
   "commit": false,
-  "fixed": [],
+  "fixed": [
+    [
+      "@zitadel/cli",
+      "@zitadel/api",
+      "@zitadel/components",
+      "@zitadel/sdk-core",
+      "@zitadel/sdk-next",
+      "@zitadel/sdk-nuxt",
+      "@zitadel/sdk-react",
+      "@zitadel/sdk-vue",
+      "@zitadel/sdk-angular"
+    ]
+  ],
   "linked": [],
   "access": "public",
   "baseBranch": "main",

.changeset/lockstep-alpha-train.md

@@ -0,0 +1,5 @@
+---
+"@zitadel/cli": patch
+---
+
+Derive alpha local runtime images from the installed CLI version, pin generated SDK dependencies to the same alpha train, and emit exact-version follow-up commands for reproducible tester reports.

.github/instructions/consumer-journey.instructions.md

@@ -12,7 +12,7 @@ demo-app e2e suite.
 - Produce package artifacts with `corepack pnpm --dir <package> pack` and keep
   tarball verification for required package presence plus unresolved
   `catalog:` or `workspace:` dependency specs.
-- Pack only the six public Zitadel packages. Private support packages such as
+- Pack only the public Zitadel packages. Private support packages such as
   design tokens must not be uploaded or published to Verdaccio.
 - Keep Verdaccio proxying npmjs for third-party dependencies while publishing
   Zitadel tarballs under both `alpha` and `latest`.

.github/instructions/typescript.instructions.md

@@ -13,7 +13,8 @@ Vitest.
   renderer props, or package entry points should include tests and README or
   contract updates when user-facing.
 - The public npm packages (`apps/cli`, `packages/api`, `packages/components`,
-  `packages/sdk-core`, `packages/sdk-next`, `packages/sdk-nuxt`) must keep
+  `packages/sdk-core`, `packages/sdk-next`, `packages/sdk-nuxt`,
+  `packages/sdk-react`, `packages/sdk-vue`, `packages/sdk-angular`) must keep
   `"license": "MIT"`.
 - User-visible changes to those packages need a changeset; write the
   `.changeset/<slug>.md` file directly rather than via the interactive prompt.

.github/workflows/ci.yml

@@ -541,14 +541,14 @@ jobs:
 
       - name: Dry-run npm packs
         run: |
-          for dir in apps/cli packages/api packages/components packages/sdk-core packages/sdk-next packages/sdk-nuxt; do
+          for dir in apps/cli packages/api packages/components packages/sdk-core packages/sdk-next packages/sdk-nuxt packages/sdk-react packages/sdk-vue packages/sdk-angular; do
             corepack pnpm --dir "$dir" pack --dry-run
           done
 
       - name: Create npm package artifacts
         run: |
           mkdir -p "$RUNNER_TEMP/zitadel-npm-packages"
-          for dir in apps/cli packages/api packages/components packages/sdk-core packages/sdk-next packages/sdk-nuxt; do
+          for dir in apps/cli packages/api packages/components packages/sdk-core packages/sdk-next packages/sdk-nuxt packages/sdk-react packages/sdk-vue packages/sdk-angular; do
             corepack pnpm --dir "$dir" pack --pack-destination "$RUNNER_TEMP/zitadel-npm-packages"
           done
           ls -lh "$RUNNER_TEMP/zitadel-npm-packages"

.github/workflows/release-npm.yml

@@ -1,10 +1,11 @@
 name: release-npm
 
-# Publishes the public npm packages (@zitadel/cli, @zitadel/api,
+# Publishes the public alpha train: npm packages (@zitadel/cli, @zitadel/api,
 # @zitadel/components, @zitadel/sdk-core, @zitadel/sdk-next, @zitadel/sdk-nuxt,
 # @zitadel/sdk-react, @zitadel/sdk-vue, @zitadel/sdk-angular)
-# via changesets. Pushing changesets to main opens a "Version Packages" PR;
-# merging that PR publishes to npm.
+# via Changesets, then the matching Go server image/binaries via GoReleaser.
+# Pushing changesets to main opens a "Version Packages" PR; merging that PR
+# publishes to npm, creates v<version>, and publishes the single GitHub Release.
 #
 # The repo is in changesets PRERELEASE mode (.changeset/pre.json, tag "alpha"),
 # so versions are cut as X.Y.Z-alpha.N and published under the `alpha` npm
@@ -39,6 +40,7 @@ on:
 permissions:
   contents: write
   pull-requests: write
+  packages: write
   id-token: write
 
 concurrency:
@@ -88,12 +90,14 @@ jobs:
         run: corepack pnpm nx run-many -t build
 
       - name: Create release PR or publish to npm
+        id: changesets
         uses: changesets/action@v1
         with:
           version: corepack pnpm changeset version
           publish: corepack pnpm changeset publish
           title: "chore: version packages"
           commit: "chore: version packages"
+          createGithubReleases: false
         env:
           # App token (not GITHUB_TOKEN) so the Version Packages PR triggers CI.
           GITHUB_TOKEN: ${{ steps.app-token.outputs.token }}
@@ -103,3 +107,87 @@ jobs:
           # Keep trusted publishing via OIDC, but disable provenance until this
           # repository is public.
           NPM_CONFIG_PROVENANCE: "false"
+
+      - name: Inspect alpha release train candidate
+        id: alpha-status
+        env:
+          PUBLISHED: ${{ steps.changesets.outputs.published }}
+        run: |
+          set -euo pipefail
+          alpha_env="$RUNNER_TEMP/alpha-release-status.env"
+          node scripts/release-alpha-train.mjs status --published "$PUBLISHED" --remote false | tee "$alpha_env"
+          cat "$alpha_env" >> "$GITHUB_OUTPUT"
+
+      - name: Login to GHCR
+        if: ${{ steps.alpha-status.outputs.should_complete == 'true' }}
+        uses: docker/login-action@v4
+        with:
+          registry: ghcr.io
+          username: ${{ github.actor }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Prepare alpha release train
+        if: ${{ steps.alpha-status.outputs.should_complete == 'true' }}
+        id: alpha
+        env:
+          PUBLISHED: ${{ steps.changesets.outputs.published }}
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          set -euo pipefail
+          alpha_env="$RUNNER_TEMP/alpha-release.env"
+          node scripts/release-alpha-train.mjs prepare --published "$PUBLISHED" --out-dir "$RUNNER_TEMP/alpha-release" | tee "$alpha_env"
+          cat "$alpha_env" >> "$GITHUB_OUTPUT"
+
+      - name: Set up QEMU
+        if: ${{ steps.alpha.outputs.run_goreleaser == 'true' }}
+        uses: docker/setup-qemu-action@v4
+
+      - name: Set up Docker Buildx
+        if: ${{ steps.alpha.outputs.run_goreleaser == 'true' }}
+        uses: docker/setup-buildx-action@v4
+
+      - name: Create and push Go release tag
+        if: ${{ steps.alpha.outputs.create_tag == 'true' }}
+        env:
+          TAG: ${{ steps.alpha.outputs.tag }}
+          TITLE: ${{ steps.alpha.outputs.title }}
+        run: |
+          set -euo pipefail
+          git config user.name "zitadel-release"
+          git config user.email "noreply@zitadel.com"
+          git tag -a "$TAG" -m "$TITLE"
+          git push origin "$TAG"
+
+      - name: Prune npm package tags for GoReleaser
+        if: ${{ steps.alpha.outputs.run_goreleaser == 'true' }}
+        run: |
+          set -euo pipefail
+          git tag -l '@zitadel/*' | while read -r tag; do
+            git tag -d "$tag"
+          done
+
+      - name: Run GoReleaser
+        if: ${{ steps.alpha.outputs.run_goreleaser == 'true' }}
+        uses: goreleaser/goreleaser-action@v7
+        with:
+          distribution: goreleaser
+          version: "~> v2"
+          args: release --clean
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Update GitHub Release notes
+        if: ${{ steps.alpha.outputs.update_release == 'true' }}
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          TAG: ${{ steps.alpha.outputs.tag }}
+          TITLE: ${{ steps.alpha.outputs.title }}
+          NOTES_PATH: ${{ steps.alpha.outputs.notes_path }}
+        run: |
+          set -euo pipefail
+          gh release edit "$TAG" \
+            --draft \
+            --prerelease \
+            --latest=false \
+            --title "$TITLE" \
+            --notes-file "$NOTES_PATH"

.goreleaser.yaml

@@ -44,8 +44,9 @@ dockers_v2:
       - 'ghcr.io/zitadel/nextgen'
     tags:
       - '{{ .Version }}'
-      # Skip `latest` for snapshots so they don't clobber the published tag.
-      - '{{ if not .IsSnapshot }}latest{{ end }}'
+      # Only stable releases move the convenience tag. Alpha/beta/rc trains
+      # must stay on their immutable version tag.
+      - '{{ if and (not .IsSnapshot) (eq .Prerelease "") }}latest{{ end }}'
     platforms:
       - linux/amd64
       - linux/arm64
@@ -70,3 +71,5 @@ changelog:
 
 release:
   draft: true
+  prerelease: auto
+  make_latest: '{{ if .Prerelease }}false{{ else }}true{{ end }}'

AGENTS.md

@@ -49,8 +49,9 @@ Secrets").
   Playwright project. It installs local package tarballs through a temporary
   registry and verifies CLI setup plus real registration/login flows.
 - `packages/components/` contains shared Lit components.
-- `packages/sdk-core/`, `packages/sdk-next/`, and `packages/sdk-nuxt/` contain
-  public TypeScript SDKs.
+- `packages/sdk-core/`, `packages/sdk-next/`, `packages/sdk-nuxt/`,
+  `packages/sdk-react/`, `packages/sdk-vue/`, and `packages/sdk-angular/`
+  contain public TypeScript SDKs.
 - `packages/api-mock/` contains the in-process MSW handlers and standalone
   mock auth server used by demos and e2e tests.
 - `packages/lint/` contains the local Nx plugin that infers Oxlint targets.
@@ -107,6 +108,8 @@ workflows.
 
 Use `corepack pnpm run check -- --full` for slower CI-parity phases and
 `corepack pnpm run check -- --only <phase>` to rerun one named phase.
+Use `corepack pnpm run check -- --only release` after touching Changesets,
+GoReleaser, release workflows, or alpha train behavior.
 
 Prefer Nx project targets for narrow package work, for example
 `corepack pnpm nx test @zitadel/cli`.
@@ -212,8 +215,9 @@ For customer-local runtime workflows, agents should prefer
   `docs` type, for example `docs: add preview status disclaimer`.
 - User-visible changes to a public npm package need a changeset. The public
   packages are `@zitadel/cli` (`apps/cli/`), `@zitadel/api`,
-  `@zitadel/components`, `@zitadel/sdk-core`, `@zitadel/sdk-next`, and
-  `@zitadel/sdk-nuxt`. CI fails a PR that touches them without one
+  `@zitadel/components`, `@zitadel/sdk-core`, `@zitadel/sdk-next`,
+  `@zitadel/sdk-nuxt`, `@zitadel/sdk-react`, `@zitadel/sdk-vue`, and
+  `@zitadel/sdk-angular`. CI fails a PR that touches them without one
   (`changeset-check` in `.github/workflows/ci.yml`).
 - Add a changeset by writing the file directly — do not depend on the
   interactive `pnpm changeset` prompt. Create `.changeset/<short-slug>.md`:
@@ -228,8 +232,9 @@ For customer-local runtime workflows, agents should prefer
 
   List only public package names; pick `patch` (fixes), `minor` (features), or
   `major` (breaking). The repo is in `alpha` prerelease mode
-  (`.changeset/pre.json`), so versions cut as `X.Y.Z-alpha.N` automatically — no
-  extra action needed.
+  (`.changeset/pre.json`) and public packages are in one fixed group, so
+  versions cut as one `X.Y.Z-alpha.N` train automatically — no extra action
+  needed.
 
 - For changes that release nothing (docs, tests, CI, chores), add an empty
   changeset: `corepack pnpm changeset --empty`.

README.md

@@ -166,9 +166,12 @@ service logs. These artifacts expire after 7 days and are not release artifacts.
 
 ## Build & release
 
-This monorepo separates Go release artifacts, console build output, and npm
-package artifacts. The full rationale lives in
-[docs/adrs/002-multi-package-release-strategy.md](docs/adrs/002-multi-package-release-strategy.md).
+This monorepo uses GoReleaser for Go artifacts and Changesets for npm package
+versioning. During the public alpha period, the release train intentionally
+publishes one version across the server image, server binary, CLI, and public
+npm packages. The full rationale lives in
+[docs/adrs/002-multi-package-release-strategy.md](docs/adrs/002-multi-package-release-strategy.md)
+and [docs/adrs/023-lockstep-alpha-release-train.md](docs/adrs/023-lockstep-alpha-release-train.md).
 
 ### Go server binary + embedded UIs (`goreleaser`)
 
@@ -186,10 +189,10 @@ docker run --rm -p 8080:8080 \
   ghcr.io/zitadel/nextgen:<snapshot-tag>-amd64
 ```
 
-The publish-capable release workflow is currently manual-only via
-`.github/workflows/release.yml` (`workflow_dispatch`). It can run a dry snapshot
-or, when intentionally invoked for a release tag, produce multi-arch tarballs and
-push a multi-arch image manifest to `ghcr.io/zitadel/nextgen`.
+The manual `.github/workflows/release.yml` workflow remains available for server
+snapshots and fallback releases. The normal public alpha path runs GoReleaser
+from [`release-npm.yml`](.github/workflows/release-npm.yml) after npm publishing
+succeeds, so the server image and npm packages share the same alpha version.
 
 ### npm packages (`changesets`)
 
@@ -201,8 +204,32 @@ change to those packages:
 corepack pnpm changeset
 ```
 
-The changesets workflow opens a "Version Packages" PR. Merging that PR versions
-and publishes the affected packages through npm trusted publishing.
+The changesets workflow opens a "Version Packages" PR. Merging that PR publishes
+the fixed alpha package group through npm trusted publishing, validates that all
+public packages share the same `0.1.0-alpha.N` version, creates `v<version>`,
+runs GoReleaser, and updates one draft GitHub Release titled
+`ZITADEL Alpha <version>`. Alpha releases are GitHub prereleases and publish only
+the immutable image tag, for example `ghcr.io/zitadel/nextgen:0.1.0-alpha.N`;
+they do not move `ghcr.io/zitadel/nextgen:latest`.
+
+Follow the short [alpha release runbook](docs/runbooks/release-alpha-train.md)
+when cutting a public alpha train.
+
+Release process checks can be run locally with:
+
+```sh
+corepack pnpm run check -- --only release
+```
+
+Tester commands use either the latest alpha stream or an exact train:
+
+```sh
+npx @zitadel/cli@alpha doctor
+npx @zitadel/cli@alpha start
+npx @zitadel/cli@alpha setup --framework next --server local
+
+npx @zitadel/cli@0.1.0-alpha.N start
+```
 
 ### Local development