feat: add lockstep alpha release train by fforootd · Pull Request #265 · zitadel/nextgen

fforootd · 2026-06-11T17:58:34Z

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:

0.1.0-alpha.N

The tester experience becomes:

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:

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

vercel · 2026-06-11T17:58:37Z

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
nextgen	Ready	Preview, Comment	Jun 12, 2026 4:03pm

Copilot

Pull request overview

Adds a “preview bundle” release flow (zitadel-preview@0.x.y) that composes already-published server + npm artifacts into a single GitHub Release manifest, and teaches the CLI to consume --preview-manifest to pin the local runtime image and scaffolded SDK dependency versions for reproducible external testing.

Changes:

Introduces a release-preview GitHub Actions workflow plus a Node script to validate artifacts, generate a preview manifest + release notes, and create a draft GitHub Release.
Adds CLI support for --preview-manifest in doctor, start, and setup, including manifest parsing/validation and dependency pinning for scaffolded apps.
Updates docs (root README, CLI docs, ADR, runbook) and adds unit/integration tests covering the new manifest behavior.

Reviewed changes

Copilot reviewed 22 out of 22 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
scripts/run-cli.mjs	Prevents auto-building the local runtime image when `--preview-manifest` is used (treats it as an image source override).
scripts/release-preview.mjs	New script to validate inputs/artifacts, resolve image digests, generate the preview manifest + release notes, and print workflow outputs.
README.md	Documents the new `zitadel-preview` bundle concept and release ceremony.
docs/runbooks/release-preview.md	New runbook describing how to cut and publish a preview bundle release.
docs/adrs/README.md	Adds ADR 023 to the ADR index.
docs/adrs/023-zitadel-preview-product-bundles.md	New ADR describing the preview bundle decision and CLI behavior.
apps/cli/tests/unit/scripts/run-cli.test.ts	Updates wrapper tests for the new `--preview-manifest` “don’t auto-build image” behavior.
apps/cli/tests/unit/scripts/release-preview.test.ts	New unit tests for the preview release script (manifest/notes generation, tag immutability, failure behavior).
apps/cli/tests/unit/lib/preview-manifest.test.ts	New unit tests for CLI preview manifest loading/validation and version/image rules.
apps/cli/tests/unit/commands/local-runtime.test.ts	Extends local-runtime command tests for `doctor/start --preview-manifest` behaviors and image selection.
apps/cli/tests/integration/setup-next.test.ts	Adds integration test ensuring `setup` pins exact SDK versions from a preview manifest.
apps/cli/src/lib/preview-manifest.ts	New manifest loader/parser/validator used by CLI commands to pin image + npm versions.
apps/cli/src/lib/orca/patchers/types.ts	Extends patch context to optionally carry pinned dependency versions.
apps/cli/src/lib/orca/patchers/rule/next/index.ts	Uses pinned dependency versions (when provided) instead of CLI-derived defaults.
apps/cli/src/lib/local-server/docker.ts	Extends container inspection to return the container image so `start` can detect mismatched images.
apps/cli/src/commands/start.ts	Adds `--preview-manifest`, uses manifest image selection, includes preview info in output, and tightens “already running” detection by matching image.
apps/cli/src/commands/setup/index.ts	Adds `--preview-manifest`, pins SDK dependency versions from manifest, and includes preview info in output.
apps/cli/src/commands/doctor/index.ts	Adds `--preview-manifest`, uses manifest image selection, and includes preview info in output.
apps/cli/SKILLS.md	Updates CLI agent guidance to include preview bundle invocation and flag usage.
apps/cli/README.md	Updates CLI documentation and generated command help snippets for `--preview-manifest`.
.github/workflows/release-preview.yml	New workflow to compose artifacts into a draft preview bundle GitHub Release.
.changeset/preview-bundle-manifest.md	Adds a changeset bumping `@zitadel/cli` for the new preview-manifest feature.

Copilot

Pull request overview

Copilot reviewed 36 out of 36 changed files in this pull request and generated 2 comments.

@mridang

This PR was opened by the [Changesets release](https://github.com/changesets/action) GitHub action. When you're ready to do a release, you can merge this and the packages will be published to npm automatically. If you're not ready to do a release yet, that's fine, whenever you add more changesets to main, this PR will be updated. ⚠️

⚠️

⚠️ `main` is currently in **pre mode** so this branch has prereleases rather than normal releases. If you want to exit prereleases, run `changeset pre exit` on `main`. ⚠️

⚠️

⚠️ # Releases ## @zitadel/components@0.1.0-alpha.2 ### Minor Changes - [#266](#266) [`01aed1e`](01aed1e) Thanks [@mridang](https://github.com/mridang)! - Allow configuring `<zitadel-login>` and `<zitadel-logout>` declaratively from HTML via `project-id`, `proxy-path`, and `url` attributes, so the components work on a plain page without JS or `configureZitadel()`. Configuration resolves in this order, highest first: the `project` property, then the `configureZitadel()` global, then the HTML attributes. The existing JS paths still win — the attributes are the no-JS fallback. Also fix the standalone bundle so it loads in a browser: it was built for Node and emitted an `import "node:module"` that browsers cannot resolve. It is now built for the browser, so `dist/standalone.mjs` is genuinely self-contained. - [#261](#261) [`09aa2b1`](09aa2b1) Thanks [@mridang](https://github.com/mridang)! - Add a standalone browser bundle (`dist/standalone.mjs`) so the components work on a plain HTML page via `<script type="module">` with no import map or bundler. Exposed via the `./standalone` export and `unpkg`/`jsdelivr`. ### Patch Changes - [#231](#231) [`ce89c59`](ce89c59) Thanks [@bastionstack](https://github.com/bastionstack)! - Tidy the web components package: align README/AGENTS docs with the real SDK-config API, adopt idiomatic Lit patterns (`classMap`, `live()`, `ifDefined`, `@query`, a shared `emit()` helper), make post-step focus deterministic via `updateComplete` instead of `requestAnimationFrame`, centralise SDK/API resolution in a `resolveApi()` helper, correct the manifest registry (e.g. `zl-passkey` `method` attribute), and expand unit/browser test coverage. - [#253](#253) [`c097a5f`](c097a5f) Thanks [@vitorbari](https://github.com/vitorbari)! - Add English labels for the `givenName`, `familyName`, and `dateOfBirth` fields the default register step now collects. ## @zitadel/cli@0.1.0-alpha.2 ### Patch Changes - [#265](#265) [`ceb74d5`](ceb74d5) Thanks [@fforootd](https://github.com/fforootd)! - 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. - [#255](#255) [`ca53f61`](ca53f61) Thanks [@fforootd](https://github.com/fforootd)! - Make doctor local-runtime checks advisory for cloud setup, harden fresh Next.js scaffolding, auto-install setup dependencies, normalize public follow-up commands, and avoid assuming Next.js in local-runtime setup guidance. - Updated dependencies [[`b0094f4`](b0094f4)]: - @zitadel/api@0.1.0-alpha.2 ## @zitadel/api@0.1.0-alpha.2 ### Patch Changes - [#268](#268) [`b0094f4`](b0094f4) Thanks [@mridang](https://github.com/mridang)! - Fix `configureZitadel()` so its state survives when more than one copy of `@zitadel/api/config` ends up loaded — the standalone components bundle inlines its own copy, and dual-package hazards / duplicate `node_modules` trees in a monorepo can load a second copy alongside the app's. Previously each module instance held its own `let currentProject`, so a `configureZitadel()` call in one was invisible to `getZitadelConfig()` in another and the components silently saw no config. The slot now lives on `globalThis` under a `Symbol.for(...)` key, which the global symbol registry resolves to the same symbol identity in every copy of the module evaluated in the same JS realm — separate realms (iframes, Node `vm` contexts, worker threads) still have their own registries. ## @zitadel/sdk-angular@0.1.0-alpha.2 ### Patch Changes - Updated dependencies [[`b0094f4`](b0094f4), [`ce89c59`](ce89c59), [`01aed1e`](01aed1e), [`09aa2b1`](09aa2b1), [`c097a5f`](c097a5f)]: - @zitadel/api@0.1.0-alpha.2 - @zitadel/components@0.1.0-alpha.2 ## @zitadel/sdk-next@0.1.0-alpha.2 ### Patch Changes - Updated dependencies [[`b0094f4`](b0094f4), [`ce89c59`](ce89c59), [`01aed1e`](01aed1e), [`09aa2b1`](09aa2b1), [`c097a5f`](c097a5f)]: - @zitadel/api@0.1.0-alpha.2 - @zitadel/components@0.1.0-alpha.2 - @zitadel/sdk-core@0.1.0-alpha.2 ## @zitadel/sdk-nuxt@0.1.0-alpha.2 ### Patch Changes - Updated dependencies [[`b0094f4`](b0094f4), [`ce89c59`](ce89c59), [`01aed1e`](01aed1e), [`09aa2b1`](09aa2b1), [`c097a5f`](c097a5f)]: - @zitadel/api@0.1.0-alpha.2 - @zitadel/components@0.1.0-alpha.2 - @zitadel/sdk-core@0.1.0-alpha.2 ## @zitadel/sdk-react@0.1.0-alpha.2 ### Patch Changes - Updated dependencies [[`b0094f4`](b0094f4), [`ce89c59`](ce89c59), [`01aed1e`](01aed1e), [`09aa2b1`](09aa2b1), [`c097a5f`](c097a5f)]: - @zitadel/api@0.1.0-alpha.2 - @zitadel/components@0.1.0-alpha.2 - @zitadel/sdk-core@0.1.0-alpha.2 ## @zitadel/sdk-vue@0.1.0-alpha.2 ### Patch Changes - Updated dependencies [[`b0094f4`](b0094f4), [`ce89c59`](ce89c59), [`01aed1e`](01aed1e), [`09aa2b1`](09aa2b1), [`c097a5f`](c097a5f)]: - @zitadel/api@0.1.0-alpha.2 - @zitadel/components@0.1.0-alpha.2 - @zitadel/sdk-core@0.1.0-alpha.2 ## @zitadel/sdk-core@0.1.0-alpha.2 Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>

Add zitadel-preview bundle release support

9e31a55

Copilot AI review requested due to automatic review settings June 11, 2026 17:58

vercel Bot deployed to Preview June 11, 2026 17:59 View deployment

Copilot started reviewing on behalf of fforootd June 11, 2026 17:59 View session

fforootd changed the title ~~Add zitadel-preview preview bundle release flow~~ feat: add zitadel-preview product bundle release flow Jun 11, 2026

Copilot AI reviewed Jun 11, 2026

View reviewed changes

Comment thread scripts/release-preview.mjs Outdated

Comment thread apps/cli/src/commands/start.ts Outdated

Comment thread apps/cli/src/commands/start.ts Outdated

Refine CLI release and onboarding workflows

1f688ac

fforootd requested a review from Copilot June 11, 2026 20:00

Copilot started reviewing on behalf of fforootd June 11, 2026 20:01 View session

Copilot AI reviewed Jun 11, 2026

View reviewed changes

Comment thread .github/workflows/release-npm.yml Outdated

Comment thread README.md

vercel Bot deployed to Preview June 11, 2026 20:07 View deployment

fforootd changed the title ~~feat: add zitadel-preview product bundle release flow~~ feat: add lockstep alpha release train Jun 11, 2026

fix: keep alpha train package versions aligned

624246f

vercel Bot deployed to Preview June 11, 2026 22:28 View deployment

Refine alpha release train and CLI follow-up commands

d36c074

vercel Bot deployed to Preview June 11, 2026 23:12 View deployment

Merge branch 'main' into codex/debate-preview-release-process

025465b

vercel Bot deployed to Preview June 12, 2026 02:21 View deployment

Merge branch 'main' into codex/debate-preview-release-process

fe19da5

fforootd enabled auto-merge (squash) June 12, 2026 16:03

vercel Bot deployed to Preview June 12, 2026 16:03 View deployment

fforootd merged commit ceb74d5 into main Jun 12, 2026
12 checks passed

fforootd deleted the codex/debate-preview-release-process branch June 12, 2026 16:07

zitadel-nextgen-release Bot mentioned this pull request Jun 12, 2026

chore: version packages (alpha) #256

Merged

fforootd mentioned this pull request Jun 12, 2026

build: refine v5 alpha release train #248

Closed

Navigation Menu

Uh oh!

feat: add lockstep alpha release train - #265

feat: add lockstep alpha release train#265
fforootd merged 6 commits into
mainfrom
codex/debate-preview-release-process

fforootd commented Jun 11, 2026 •

edited

Loading

Uh oh!

vercel Bot commented Jun 11, 2026 •

edited

Loading

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Uh oh!

Conversation

fforootd commented Jun 11, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

What changed against main

Why

Validation

Uh oh!

vercel Bot commented Jun 11, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

fforootd commented Jun 11, 2026 •

edited

Loading

vercel Bot commented Jun 11, 2026 •

edited

Loading