Add zitadel-preview bundle release support

Author: fforootd

.changeset/preview-bundle-manifest.md

@@ -0,0 +1,5 @@
+---
+"@zitadel/cli": minor
+---
+
+Add zitadel-preview manifest support for pinning tested server images and SDK package versions.

.github/workflows/release-preview.yml

@@ -0,0 +1,118 @@
+name: release-preview
+
+# Composes already-published artifacts into a customer-facing
+# `zitadel-preview@0.x.y` bundle. This workflow does not publish npm packages
+# and does not run GoReleaser; it verifies existing artifacts and creates a
+# draft GitHub Release with a manifest asset.
+
+on:
+  workflow_dispatch:
+    inputs:
+      preview_version:
+        description: "Preview bundle version, for example 0.1.0."
+        required: true
+        type: string
+      ref:
+        description: "Git ref to attach the preview release to."
+        required: true
+        default: "main"
+        type: string
+      server_image:
+        description: "Immutable server image ref, for example ghcr.io/zitadel/nextgen:v0.1.0-alpha.3."
+        required: true
+        type: string
+      cli_version:
+        description: "Exact @zitadel/cli npm version."
+        required: true
+        type: string
+      sdk_next_version:
+        description: "Exact @zitadel/sdk-next npm version."
+        required: true
+        type: string
+      npm_packages_json:
+        description: "Optional JSON object of extra npm package versions, for example {\"@zitadel/sdk-react\":\"0.1.0-alpha.0\"}."
+        required: false
+        default: "{}"
+        type: string
+      release_notes_path:
+        description: "Optional repository path to Markdown release notes to include before generated details."
+        required: false
+        default: ""
+        type: string
+
+permissions:
+  contents: write
+  packages: read
+
+jobs:
+  compose:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v6
+        with:
+          ref: ${{ inputs.ref }}
+          fetch-depth: 0
+
+      - name: Set up Node.js
+        uses: actions/setup-node@v6
+        with:
+          node-version-file: .nvmrc
+          registry-url: "https://registry.npmjs.org"
+
+      - name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@v4
+
+      - name: Login to GHCR
+        uses: docker/login-action@v4
+        with:
+          registry: ghcr.io
+          username: ${{ github.actor }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Generate preview manifest and notes
+        id: preview
+        env:
+          PREVIEW_VERSION: ${{ inputs.preview_version }}
+          SERVER_IMAGE: ${{ inputs.server_image }}
+          CLI_VERSION: ${{ inputs.cli_version }}
+          SDK_NEXT_VERSION: ${{ inputs.sdk_next_version }}
+          NPM_PACKAGES_JSON: ${{ inputs.npm_packages_json }}
+          RELEASE_NOTES_PATH: ${{ inputs.release_notes_path }}
+        run: |
+          set -euo pipefail
+          mkdir -p dist/preview-release
+          COMMIT="$(git rev-parse HEAD)"
+          ARGS=(
+            prepare
+            --preview-version "$PREVIEW_VERSION"
+            --commit "$COMMIT"
+            --server-image "$SERVER_IMAGE"
+            --cli-version "$CLI_VERSION"
+            --sdk-next-version "$SDK_NEXT_VERSION"
+            --additional-npm-packages-json "$NPM_PACKAGES_JSON"
+            --repository "${GITHUB_REPOSITORY}"
+            --out-dir "dist/preview-release"
+          )
+          if [ -n "$RELEASE_NOTES_PATH" ]; then
+            ARGS+=(--release-notes-path "$RELEASE_NOTES_PATH")
+          fi
+          node scripts/release-preview.mjs "${ARGS[@]}" | tee dist/preview-release.env
+          cat dist/preview-release.env >> "$GITHUB_OUTPUT"
+
+      - name: Create draft GitHub Release
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          TAG: ${{ steps.preview.outputs.tag }}
+          TITLE: ${{ steps.preview.outputs.title }}
+          MANIFEST_PATH: ${{ steps.preview.outputs.manifest_path }}
+          ASSET_NAME: ${{ steps.preview.outputs.asset_name }}
+          NOTES_PATH: ${{ steps.preview.outputs.notes_path }}
+        run: |
+          set -euo pipefail
+          gh release create "$TAG" \
+            "$MANIFEST_PATH#$ASSET_NAME" \
+            --draft \
+            --target "$(git rev-parse HEAD)" \
+            --title "$TITLE" \
+            --notes-file "$NOTES_PATH"

README.md

@@ -204,6 +204,37 @@ corepack pnpm changeset
 The changesets workflow opens a "Version Packages" PR. Merging that PR versions
 and publishes the affected packages through npm trusted publishing.
 
+### Preview product bundles (`zitadel-preview`)
+
+`zitadel-preview@0.x` is the customer-facing bundle layer for external testers.
+It does not replace the GoReleaser or Changesets workflows; it records the exact
+server image and npm package versions that were tested together.
+
+Release ceremony:
+
+1. Merge normal feature and fix PRs with changesets as usual.
+2. Let [`release-npm.yml`](.github/workflows/release-npm.yml) publish the npm
+   prerelease packages.
+3. Run [`release.yml`](.github/workflows/release.yml) for the server image.
+4. Run [`release-preview.yml`](.github/workflows/release-preview.yml) with:
+   - `preview_version`, for example `0.1.0`;
+   - immutable `server_image`, for example `ghcr.io/zitadel/nextgen:v0.1.0-alpha.3`;
+   - exact `cli_version` and `sdk_next_version`;
+   - optional extra npm packages as JSON.
+
+Follow the short [preview release runbook](docs/runbooks/release-preview.md)
+when cutting a bundle.
+
+The preview workflow creates a draft GitHub Release tagged
+`zitadel-preview-v<version>` with a `zitadel-preview-<version>.json` manifest
+asset and generated tester commands:
+
+```sh
+npx @zitadel/cli@<exact-cli-version> doctor --preview-manifest <manifest-url>
+npx @zitadel/cli@<exact-cli-version> start --preview-manifest <manifest-url>
+npx @zitadel/cli@<exact-cli-version> setup --framework next --server local --preview-manifest <manifest-url>
+```
+
 ### Local development
 
 The devcontainer at [.devcontainer/](.devcontainer/) pins Go 1.26 and a PostgreSQL sidecar.

apps/cli/README.md

@@ -28,13 +28,24 @@ npm run dev
 
 `start` runs a Docker-backed local Zitadel server and stores runtime data
 under `.zitadel/local/`. It uses `ghcr.io/zitadel/nextgen:latest` unless
-overridden with `--image` or `ZITADEL_LOCAL_IMAGE`. `setup --server local`
-creates a project on that local server, scaffolds `app/login`, `app/register`, and
-`middleware.ts`, writes `.env.local` and `.zitadel/`, and installs dependencies
-with the detected package manager. Pass `--skip-install` to install them
-yourself. The project's default user schema and login flow are provisioned
-server-side at creation time, so the CLI does not scaffold or upload them.
-Open `http://localhost:3000/login` to see the login page.
+overridden with `--image`, `--preview-manifest`, or `ZITADEL_LOCAL_IMAGE`.
+`setup --server local` creates a project on that local server, scaffolds
+`app/login`, `app/register`, and `middleware.ts`, writes `.env.local` and
+`.zitadel/`, and installs dependencies with the detected package manager. Pass
+`--skip-install` to install them yourself. The project's default user schema
+and login flow are provisioned server-side at creation time, so the CLI does
+not scaffold or upload them. Open `http://localhost:3000/login` to see the
+login page.
+
+For a `zitadel-preview` bundle, use the exact manifest URL from the GitHub
+Release so the CLI starts the tested server image and scaffolds the tested SDK
+versions:
+
+```sh
+npx @zitadel/cli@<exact-version> doctor --preview-manifest <manifest-url>
+npx @zitadel/cli@<exact-version> start --preview-manifest <manifest-url>
+npx @zitadel/cli@<exact-version> setup --framework next --server local --preview-manifest <manifest-url>
+```
 
 The default project flow supports password registration/login, passkey
 registration/login, and optional passkey setup after password registration.
@@ -138,7 +149,7 @@ Verify local runtime and project state.
 ```
 USAGE
   $ zitadel doctor [--json] [-c <value>] [-s <value>] [-n] [-f] [--dry-run] [--verbose] [--debug] [--fix]
-    [--image <value>] [--port <value>]
+    [--image <value>] [--port <value>] [--preview-manifest <value>]
 
 FLAGS
   -c, --cwd=<value>      Project directory to operate on.
@@ -150,6 +161,8 @@ FLAGS
       --fix              Re-apply missing managed files.
       --image=<value>    Container image to check.
       --port=<value>     [default: 8080] Local HTTP port.
+      --preview-manifest=<value>
+                          Path or URL to a zitadel-preview manifest.
       --verbose          Verbose logging.
 
 GLOBAL FLAGS
@@ -280,7 +293,7 @@ Create a Zitadel project and scaffold local auth.
 ```
 USAGE
   $ zitadel setup [--json] [-c <value>] [-s <value>] [-n] [-f] [--dry-run] [--verbose] [--debug]
-    [--framework next] [--renderer react|web-component] [--skip-install]
+    [--framework next] [--renderer react|web-component] [--skip-install] [--preview-manifest <value>]
 
 FLAGS
   -c, --cwd=<value>         Project directory to operate on.
@@ -291,6 +304,8 @@ FLAGS
       --dry-run             Preview without mutating files or the platform.
       --framework=<option>  Framework to target.
                             <options: next>
+      --preview-manifest=<value>
+                            Path or URL to a zitadel-preview manifest.
       --renderer=<option>   Renderer (default: react).
                             <options: react|web-component>
       --skip-install        Do not install dependencies after setup updates package.json.
@@ -313,7 +328,7 @@ Start a local Zitadel server.
 ```
 USAGE
   $ zitadel start [--json] [-c <value>] [-s <value>] [-n] [-f] [--dry-run] [--verbose] [--debug] [--image
-    <value>] [--port <value>]
+    <value>] [--port <value>] [--preview-manifest <value>]
 
 FLAGS
   -c, --cwd=<value>      Project directory to operate on.
@@ -324,6 +339,8 @@ FLAGS
       --dry-run          Preview without mutating files or the platform.
       --image=<value>    Container image to run.
       --port=<value>     [default: 8080] Local HTTP port.
+      --preview-manifest=<value>
+                          Path or URL to a zitadel-preview manifest.
       --verbose          Verbose logging.
 
 GLOBAL FLAGS

apps/cli/SKILLS.md

@@ -68,6 +68,11 @@ layer, not the envelope.
 - `reset` — stop/remove the managed container and delete local runtime data;
   requires `--force` when non-interactive.
 
+For an external `zitadel-preview` bundle, pass
+`--preview-manifest <path-or-url>` to `doctor`, `start`, and `setup`. The
+manifest pins the server image and SDK package versions that were tested
+together. `zitadel start --image <ref>` remains the explicit image override.
+
 ## Golden path
 
 ```sh
@@ -79,6 +84,14 @@ npx @zitadel/cli@alpha plan --non-interactive --json
 npx @zitadel/cli@alpha apply --non-interactive --json
 ```
 
+Preview bundle invocation:
+
+```sh
+npx @zitadel/cli@<exact-version> doctor --preview-manifest <manifest-url> --non-interactive --json
+npx @zitadel/cli@<exact-version> start --preview-manifest <manifest-url> --non-interactive --json
+npx @zitadel/cli@<exact-version> setup --framework next --server local --preview-manifest <manifest-url> --non-interactive --json
+```
+
 Repo config is authoritative: edit `zitadel.json` or files under `.zitadel/`,
 then re-run `plan` and `apply`. Managed files carry a marker comment; `eject`
 removes only files that still carry it, preserving anything the user replaced.

apps/cli/src/commands/doctor/index.ts

@@ -15,6 +15,7 @@ import {
 } from "../../lib/local-server/runtime";
 import { BaseCommand, type JsonEnvelope } from "../../lib/oclif";
 import { createOrca } from "../../lib/orca";
+import { loadPreviewManifest, previewServerImage } from "../../lib/preview-manifest";
 import { hasZitadelConfig } from "../../lib/project";
 import { publicCliCommand } from "../../lib/public-cli";
 import { SANITY_CHECKS, type CheckContext, type CheckOutcome } from "./checks";
@@ -40,14 +41,24 @@ export default class Doctor extends BaseCommand {
     fix: Flags.boolean({ description: "Re-apply missing managed files." }),
     image: Flags.string({ description: "Container image to check." }),
     port: Flags.integer({ description: "Local HTTP port.", default: DEFAULT_LOCAL_SERVER_PORT }),
+    "preview-manifest": Flags.string({
+      description: "Path or URL to a zitadel-preview manifest.",
+    }),
   };
 
   async run(): Promise<JsonEnvelope> {
     const { flags } = await this.parse(Doctor);
     const port = flags.port ?? DEFAULT_LOCAL_SERVER_PORT;
     await this.toMeta(flags, { resolveServer: false, source: localServerUrl(port) });
     const { cwd, dryRun } = this.meta;
-    const image = flags.image ?? this.meta.env.ZITADEL_LOCAL_IMAGE ?? DEFAULT_LOCAL_SERVER_IMAGE;
+    const preview = flags["preview-manifest"]
+      ? await loadPreviewManifest(flags["preview-manifest"], cwd)
+      : undefined;
+    const image =
+      flags.image ??
+      (preview ? previewServerImage(preview) : undefined) ??
+      this.meta.env.ZITADEL_LOCAL_IMAGE ??
+      DEFAULT_LOCAL_SERVER_IMAGE;
     const runtimeChecks = await runLocalRuntimeChecks(cwd, image, port);
     const hasConfig = await hasZitadelConfig(cwd);
     const ctx: CheckContext = { cwd, orca: createOrca(), cliVersion: this.meta.cliVersion, dryRun };
@@ -82,6 +93,12 @@ export default class Doctor extends BaseCommand {
       ok: failed.length === 0,
       image,
       port,
+      preview: preview
+        ? {
+            product: preview.product,
+            manifest: flags["preview-manifest"],
+          }
+        : undefined,
       project: {
         lifecycle: hasConfig ? "configured" : "not-configured",
       },

apps/cli/src/commands/setup/index.ts

@@ -9,6 +9,7 @@ import { BaseCommand, type JsonEnvelope } from "../../lib/oclif";
 import { createOrca, issuerFromPort, type FrameworkFacts, type Orca } from "../../lib/orca";
 import { RENDERER_IDS } from "../../lib/orca/patchers/rule/next/renderers/registry";
 import type { PatchContext } from "../../lib/orca/patchers/types";
+import { loadPreviewManifest, previewNpmVersions } from "../../lib/preview-manifest";
 import { hasZitadelConfig, hasZitadelSecret } from "../../lib/project";
 import { installDependenciesForSetup } from "./install";
 import { PickFrameworkPrompt, SETUP_PROMPTS, type SetupAnswers } from "./prompts";
@@ -58,12 +59,19 @@ export default class Setup extends BaseCommand {
     "skip-install": Flags.boolean({
       description: "Do not install dependencies after setup updates package.json.",
     }),
+    "preview-manifest": Flags.string({
+      description: "Path or URL to a zitadel-preview manifest.",
+    }),
   };
 
   async run(): Promise<JsonEnvelope> {
     const { flags } = await this.parse(Setup);
     await this.toMeta(flags);
     const { cwd, nonInteractive, dryRun, force } = this.meta;
+    const preview = flags["preview-manifest"]
+      ? await loadPreviewManifest(flags["preview-manifest"], cwd)
+      : undefined;
+    const dependencyVersions = preview ? previewNpmVersions(preview) : undefined;
 
     if (await hasZitadelConfig(cwd)) {
       return this.emit({ status: "skipped", reason: "already-initialized" });
@@ -135,6 +143,7 @@ export default class Setup extends BaseCommand {
       issuer,
       server: answers.server,
       cliVersion: this.meta.cliVersion,
+      dependencyVersions,
     };
     consola.start(`Patching project files${dryRun ? " (dry run)" : ""}`);
     const result = await orca.patcherFor(framework.id).patch(ctx, { cwd, dryRun, force });
@@ -201,6 +210,12 @@ export default class Setup extends BaseCommand {
         files_written: result.filesWritten.map((file) => relativeDisplay(cwd, file)),
         files_skipped: result.filesSkipped.map((file) => relativeDisplay(cwd, file)),
         install: installOutcome.install,
+        preview: preview
+          ? {
+              product: preview.product,
+              manifest: flags["preview-manifest"],
+            }
+          : undefined,
         next_actions: installOutcome.nextActions,
         next_commands: installOutcome.nextCommands,
       },