---
title: Deploy apps with preview tracks
slug: optimizely-connect-platform/docs/preview-tracks
createdAt: 2026-10-05T12:00:00.000Z
---

A preview track is a named line of an Optimizely Connect Platform (OCP) app, such as `dev/jdoe` or `beta/feature-x`. Deploying to a track builds and publishes your app in one command. You do not edit the `version` field in `app.yml`, and you do not run `ocp app prepare` and `ocp directory publish` separately. Preview tracks and the `ocp app deploy`, `ocp app promote`, and `ocp app rollback` commands are the standard way to deploy and release an app. Release versions still go through the [app review process](https://docs.optimizely.com/optimizely-connect-platform/docs/releasing#app-review-process).

Preview tracks replace the legacy `-dev` and `-beta` [pre-release versions](https://docs.optimizely.com/optimizely-connect-platform/docs/app-versioning-ocp2#pre-release-tag) you use while you build an app. Use [semantic versioning](https://docs.optimizely.com/optimizely-connect-platform/docs/app-versioning-ocp2) (semver) to release an app:

- **Semver versions, such as** `1.2.0` – Reviewed, listed in the OCP **App Directory**, and auto-upgraded by MAJOR, MINOR, and PATCH ordering. Public releases use them.
- **Preview track versions, such as** `dev/jdoe/abc1234` – Installed only into the accounts you choose, never reviewed, and listed in the **App Directory** only for the accounts that install or follow them.

Pre-release versions, and the `version` field in `app.yml`, only matter for apps that still release with the deprecated `ocp app prepare` command. Use preview tracks for day-to-day development and testing. Use semver versions for releases.

An installation can follow a track. An installation that follows a track upgrades to each version you deploy to that track, so you do not reinstall after each change.

With a preview track, the version is no longer part of your code. OCP derives it from your app content, and your test accounts follow the track, so you do not pick a version number, edit `app.yml`, or reinstall after each change. The loop is: edit your app, run `ocp app deploy`, check the result in your test account, repeat. You choose a version number when you are ready to release the app to production.

## Preview track requirements

An app can deploy to a preview track when it meets the following requirements:

- `app.yml` declares `runtime: node22` or later. See the [Node22 migration guide](https://docs.optimizely.com/optimizely-connect-platform/docs/node22-migration).
- `package.json` depends on `@zaiusinc/app-sdk` 3 or later.

Apps that do not meet these requirements cannot deploy to a preview track. An app on `runtime: node22` or later can still release a semver version with `ocp app deploy --version`. `ocp app deploy` refuses apps on earlier runtimes and says so. Those apps keep releasing with the deprecated `ocp app prepare` command until they migrate.

## Preview version identifier

A preview version is identified by `TRACK/SHA`, such as `dev/jdoe/abc1234`. The identifier has the following parts:

- `TRACK` – The track name, made of a lane (the `dev` or `beta` prefix) and a name, such as `dev/jdoe` or `beta/feature-x`.
- `SHA` – A seven-character hash of your app content.

Because the version follows the content, you do not choose or bump it:

- Change a file in your app, or a value in `.env`, and the next deploy creates a version.
- Deploy with nothing changed and OCP keeps the version you already have, without building it again.

## Deploy to a preview track

Run the following command from your app directory:

```shell
ocp app deploy
```

With no flags, the deploy targets your personal track, `dev/USERNAME`, where `USERNAME` is the username on your developer account. Run `ocp accounts whoami` to see it.

The command builds and publishes the version, and reports each step as it runs:

```text
Deploying dev/jdoe/95544ac...
Uploading package...
Registering dev/jdoe/95544ac (us)...
Starting build...
Waiting for build (id=17191) to complete... CTRL+C to stop checking.
Build complete.
Publishing dev/jdoe/95544ac (us)...
dev/jdoe/95544ac is running (us).
No installations follow dev/jdoe yet. Install one with:
  ocp directory install my_app --preview-track dev/jdoe <trackerId> -a us

Deployed dev/jdoe/95544ac.
```

To deploy to a shared line instead of your personal one, pass a `beta` track:

```shell
ocp app deploy --preview-track beta/feature-x
```

The deploy blocks until the version is running. If the build fails, the CLI prints the build errors and stops without publishing.

:::hint{type="info"}
**Note**

`ocp app deploy` ignores the `version` field in `app.yml` and prints a warning when the field is present. Remove it from apps you deploy to preview tracks.
:::

### Deploy flags

`ocp app deploy` accepts the following flags:

- `--previewTrack` or `--preview-track` – Track to deploy to. Defaults to `dev/USERNAME`.
- `--version` – Release this semver version instead of deploying to a track, such as `1.2.0`. Cannot be combined with `--preview-track`, `--force`, or `--rc-dependencies`.
- `--watch` – With `--version`, wait for review approval and publish when it arrives.
- `--force` or `-f` – Build a version even when identical source is already deployed.
- `--rcDependencies` or `--rc-dependencies` – Build with the unstable release candidate (RC) OCP dependency set.
- `--upgradeDeps` or `--upgrade-deps` – Update out-of-date OCP dependencies before building.
- `--noPrompt` or `--no-prompt` – Use the default answer for any prompt.
- `--noProgress` or `--no-progress` – Do not display progress indicators.
- `--path` or `-p` – Root directory of the app. Defaults to the current directory.

### Resume an interrupted deploy

Re-run `ocp app deploy` after a failure or an interruption. The deploy continues from where it stopped instead of starting over, and reports that there is nothing to do when the version is already running.

To create a version from unchanged source, such as when you want a clean build, run `ocp app deploy --force`.

### List deployments

To see the app's versions grouped by track, run:

```shell
ocp app deploy list
```

The command returns an output like the following:

```text
beta/feature-x
  beta/feature-x/2691f71  PUBLISHED
dev/jdoe
  dev/jdoe/f56ffd5  PUBLISHED
  dev/jdoe/2691f71  UNPUBLISHED
(semver releases)
  1.2.0        PUBLISHED
  1.1.0        UNPUBLISHED
```

Each track holds one live version. The versions it ran before stay listed as `UNPUBLISHED` while they remain [rollback](https://docs.optimizely.com/optimizely-connect-platform/docs/preview-tracks#roll-back-a-track) targets.

## Install and follow a track

An installation follows a track instead of pinning a version. Install once, then every deploy to that track moves the installation to the version you deployed.

```shell
ocp directory install my_app TRACKER_ID
```

Without a version and without `--preview-track`, the installation follows your own `dev/USERNAME` track. To follow a shared track, pass it with `--preview-track`:

```shell
ocp directory install my_app --preview-track beta/qa TRACKER_ID
```

Replace `TRACKER_ID` with the [tracker ID](https://docs.optimizely.com/optimizely-connect-platform/docs/retrieve-your-tracker-id) of the account to install into. The command confirms the following:

```text
Installed my_app dev/jdoe/2691f71 for Z6jCndly_E2WzpvDkcKBKA (following dev/jdoe) with install id 6737
```

:::hint{type="info"}
**Note**

Pass either a version or `--preview-track`, not both. You cannot pin an installation to a specific preview version, such as `my_app@dev/jdoe/2691f71`, because a preview version is only reachable through its track.
:::

After you deploy to a followed track, the deploy summary reports how many installations moved to the version:

```text
Publishing dev/jdoe/f56ffd5 (us)...
dev/jdoe/f56ffd5 is running (us).
Rebound 1/1 installations on dev/jdoe (us).
```

The summary is a count only. It does not name the accounts that follow the track, because they can include accounts you cannot access.

Installations pinned to a semver version are unaffected by a deploy to a track. To move an installation off a track and back onto a semver version, use `ocp directory upgrade`. To move it back onto a track, run `ocp directory upgrade` with `--preview-track`.

## Release a semver version

When you are ready to release, run `ocp app deploy` with the semver version from your app directory:

```shell
ocp app deploy --version 1.2.0
```

The command builds the release version from your working directory with the release dependencies, and publishes the version. If your app is publicly listed, the command starts the app review process and publishes the version when Optimizely approves it. If your app is not publicly listed, the command publishes the version after the build with no review. It replaces `ocp app prepare` and `ocp directory publish`. You do not set the version in `app.yml`.

For a publicly listed app, review approval takes one to two business days. Without `--watch`, the first run stops at the review. After approval, rerun the same command to publish. Add `--watch` to keep waiting for approval and publish when it arrives:

```shell
ocp app deploy --version 1.2.0 --watch
```

To release the code a track already runs instead of your working directory, promote the track to a semver version. See [Promote a version](https://docs.optimizely.com/optimizely-connect-platform/docs/preview-tracks#promote-a-version).

## Promote a version

Promotion moves a version you already built to another line without rebuilding it.

To promote the current version of one track onto another track, run:

```shell
ocp app promote --from dev/jdoe --to beta/release-1.2
```

The tracks then run the same version. OCP does not rebuild anything. The target must be a `beta/` track. Promoting again advances the target to the source's current version, and the CLI reports promoting the same version twice as already promoted. The source version must be running.

To promote a specific version instead of a track's current one, run:

```shell
ocp app promote --from dev/jdoe/abc1234 --to beta/qa
```

As an alternative to `ocp app deploy --version`, promote a track to a semver target. A promotion to a semver version is a release, not a copy. It rebuilds the source the track runs with the release dependencies, starts the app review process, and publishes the version when it is approved:

```shell
ocp app promote --from dev/jdoe --to 1.2.0
```

As with `ocp app deploy --version`, the first run stops at the review unless you add `--watch`. After approval, rerun the same command to publish. Add `--watch` to keep waiting for approval and publish when it arrives. Preview deploys, track-to-track promotions, and rollbacks never enter review.

## Roll back a track

Rolling back returns a track to a version it ran before, and moves the installations that follow the track onto it. Nothing is built again. To roll back your own `dev/USERNAME` track, run the command without `--preview-track`:

```shell
ocp app rollback
```

To roll back a shared track, pass it with `--preview-track`. The flag accepts `beta/` tracks only:

```shell
ocp app rollback --preview-track beta/qa
```

With no `--to` flag, the track returns to the version it was on before its current one. To choose a target, pass its hash:

```shell
ocp app rollback --to abc1234
```

To see what you can roll back to, run:

```shell
ocp app rollback list
```

The command lists the track's versions newest-first, marks the current one, and shows which versions are still rollback targets. Without `--preview-track`, it lists your own `dev/USERNAME` track. Unlike `ocp app rollback`, it accepts any developer's `dev/` track, such as `ocp app rollback list --preview-track dev/jsmith`.

:::hint{type="info"}
**Note**

A version stays a rollback target for seven days after the track moves off it. Past that, rolling back to it fails and you deploy again instead.
:::

`ocp app rollback` applies to preview tracks only. To change a production semver version, release a version instead.

## Preview tracks and the App Directory

The public catalog lists released semver versions only. The **App Directory** lists a preview version only for the accounts that install or follow it, so other customers cannot find or install it. Browsing or installing an existing semver app is unchanged.

An account that follows a track sees the version it runs, such as `dev/jdoe/f56ffd5`, in the **App Directory** and in `ocp directory info`. Lists that mix preview and semver versions are ordered by creation time.

OCP removes preview versions that no track runs and no installation follows once they are past the seven-day rollback window. Semver versions are kept.

## Preview track limits

The following limits apply to preview tracks:

- **Version identifier length** – 32 characters, including the track and the seven-character hash.
- **Track name length** – 24 characters, which leaves 20 characters after `dev/` and 19 after `beta/`.
- **Track characters** – Lowercase letters, digits, `.`, `_`, and `-`.
- **Track lanes** – `dev` and `beta` only.
- **Rollback window** – Seven days after the track moves off a version.

Preview versions do not count against the [version limits](https://docs.optimizely.com/optimizely-connect-platform/docs/app-versioning-ocp2#version-limits) that apply to semver versions, so a deploy never fails because the app already has five `-dev` versions. Each track holds one live version, which the next deploy to that track replaces.

A `dev/` track is bound to its owner. Deploying to a track whose name is not your username is refused.

```text
The preview track 'dev/jsmith' belongs to another developer.
```

The CLI rejects a malformed track name before it starts the deploy:

```text
preview track 'Dev/JDoe' must start with 'dev/' or 'beta/'
preview track 'dev/j doe' may only contain lowercase letters, digits, '.', '_' and '-'
preview track 'dev' must be '<dev|beta>/<name>', e.g. dev/jdoe
preview track 'beta/aaaaaaaaaaaaaaaaaaaa' is 25 characters; the limit is 24 (a version is at most 32)
```

## Compare preview tracks with the legacy prepare and publish flow

The following table compares preview tracks with the deprecated `ocp app prepare` flow:

| **Feature**                 | `ocp app prepare` and `ocp directory publish` | `ocp app deploy` to a preview track                           |
| --------------------------- | --------------------------------------------- | ------------------------------------------------------------- |
| **Version source**          | The `version` field in `app.yml`              | Derived from your app's content, `TRACK/SHA`                  |
| **Commands to ship**        | Two                                           | One                                                           |
| **Version bump per change** | Manual                                        | Automatic                                                     |
| **Installations**           | Pinned to a version                           | Follow a track                                                |
| **Review**                  | Release versions enter review                 | Never                                                         |
| **App Directory catalog**   | Released semver versions are listed           | Listed only for the accounts that install or follow the track |
| **Rollback**                | Not available                                 | `ocp app rollback` within the rollback window                 |

`ocp app prepare` is deprecated. It still works and prints a deprecation warning, but it requires a `version` in `app.yml`, which apps created with `ocp app init` do not have. To release an app that declares `runtime: node22` or later, run `ocp app deploy --version` or `ocp app promote --to VERSION`. See [Release a semver version](https://docs.optimizely.com/optimizely-connect-platform/docs/preview-tracks#release-a-semver-version). A semver release does not require `@zaiusinc/app-sdk` 3. Apps on earlier runtimes keep using `ocp app prepare` until they migrate to `node22`.

## Related pages

- [App versioning](https://docs.optimizely.com/optimizely-connect-platform/docs/app-versioning-ocp2)
- [Test your app](https://docs.optimizely.com/optimizely-connect-platform/docs/testing)
- [Release your app](https://docs.optimizely.com/optimizely-connect-platform/docs/releasing)
- [OCP CLI command reference](https://docs.optimizely.com/optimizely-connect-platform/docs/ocp-cli-command-reference)
