Deploy apps with preview tracks
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.
Preview tracks replace the legacy -dev and -beta pre-release versions you use while you build an app. Use semantic versioning (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.
- 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:
ocp app deployWith 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:
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:
ocp app deploy --preview-track beta/feature-xThe deploy blocks until the version is running. If the build fails, the CLI prints the build errors and stops without publishing.
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:
ocp app deploy listThe command returns an output like the following:
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 UNPUBLISHEDEach track holds one live version. The versions it ran before stay listed as UNPUBLISHED while they remain rollback 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.
ocp directory install my_app TRACKER_IDWithout a version and without --preview-track, the installation follows your own dev/USERNAME track. To follow a shared track, pass it with --preview-track:
ocp directory install my_app --preview-track beta/qa TRACKER_IDReplace TRACKER_ID with the tracker ID of the account to install into. The command confirms the following:
Installed my_app dev/jdoe/2691f71 for Z6jCndly_E2WzpvDkcKBKA (following dev/jdoe) with install id 6737Note
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:
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:
ocp app deploy --version 1.2.0The 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:
ocp app deploy --version 1.2.0 --watchTo release the code a track already runs instead of your working directory, promote the track to a semver version. See 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:
ocp app promote --from dev/jdoe --to beta/release-1.2The 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:
ocp app promote --from dev/jdoe/abc1234 --to beta/qaAs 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:
ocp app promote --from dev/jdoe --to 1.2.0As 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:
ocp app rollbackTo roll back a shared track, pass it with --preview-track. The flag accepts beta/ tracks only:
ocp app rollback --preview-track beta/qaWith no --to flag, the track returns to the version it was on before its current one. To choose a target, pass its hash:
ocp app rollback --to abc1234To see what you can roll back to, run:
ocp app rollback listThe 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.
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 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.
The preview track 'dev/jsmith' belongs to another developer.The CLI rejects a malformed track name before it starts the deploy:
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. A semver release does not require @zaiusinc/app-sdk 3. Apps on earlier runtimes keep using ocp app prepare until they migrate to node22.