App versioning

16 min

Optimizely Connect Platform (OCP) uses the following format for app versioning: <app_name>@<app_version>. Where <app_version> consists of the version number and pre-release tag.

For example, if your app name is my_new_marketing_app, your app version is 0.0.0, and you are currently testing the first iteration of your pre-release dev app, your app's version format would look like, [email protected].

Note

You choose a version number only when you release an app, with ocp app deploy --version or ocp app promote --to. Apps that deploy with ocp app deploy have no version field in app.yml. While you build an app, you deploy to a preview track instead of a pre-release version. The version field in app.yml and the -dev, -beta, and -private pre-release tags are legacy. They only matter for apps that still release with the deprecated ocp app prepare command, such as apps on a runtime earlier than node22.

Version number

OCP apps use the following Semantic Versioning (SemVer) specification. Given a version number MAJOR.MINOR.PATCH, increment

the MAJOR version when you make an incompatible API change.

the MINOR version when you add functionality in a backward-compatible manner.

the PATCH version when you make backward-compatible bug fixes.

Note

When you update your app version, make sure you update all external API call headers.

Upgrading from one MINOR version to another is performed automatically when the new app version is published. For example, if you have published app version 1.0.0 and then publish 1.0.1, the functions onUpgrade and onFinalizeUpgrade in the Lifecycle.ts file are executed automatically for every install on every client account.

However, upgrading from one MAJOR version to another is not performed automatically when the new app version is published. For example, if you have published app version 1.0.0 and then publish 2.0.0, the functions onUpgrade and onFinalizeUpgrade in the Lifecycle.ts file are executed when the client end-user manually clicks Upgrade in the OCP App Directory UI.

Preview track versions

Instead of bumping a pre-release tag for each iteration, deploy an app to a preview track, such as dev/jdoe or beta/feature-x. A preview version is identified by TRACK/SHA, such as dev/jdoe/abc1234, where SHA is a seven-character hash of your app content. Deploying to a track builds and publishes in one command:

ocp app deploy

Preview tracks replace the legacy -dev and -beta pre-release versions you use while you build an app. Use the semantic versioning described on this page to release an app:

Preview versions – OCP never reviews them. Accounts install them only by following their track, and the OCP App Directory lists them only for those accounts.

Semver versions – They keep the behavior described on this page, including the review process and auto-upgrade ordering. Releases use them.

Preview tracks are the standard way to deploy an app while you build it. Existing -dev, -beta, and -private versions and their installations continue to work, but you cannot create versions with those tags through ocp app deploy or ocp app promote. ocp app deploy requires runtime: node22 or later in app.yml.

See Deploy apps with preview tracks for details.

Pre-release tag

Legacy

Pre-release tags only apply to the deprecated ocp app prepare flow. Deploy to a preview track instead. ocp app deploy --version and ocp app promote --to reject versions with a -dev, -beta, or -private tag.

OCP uses the following pre-release tag, which releases your app to only your private production account.

-dev – Versions with a -dev tag are intended for internal testing of your apps, are limited to running in your associated OCP account, are not shareable, and let you bypass the app review process.

Any app with the -dev pre-release tag is not globally visible inside the App Directory and is intended to serve as a work in progress.

Pre-release versioning

Pre-release versioning lets you work on a single train of code that is consistently named MAJOR.MINOR.PATCH, where you increment the pre-release tag as necessary until you are ready for your production release.

For example, imagine your next OCP app release is 2.1.9. During your development work, you end up with four pre-release dev versions before you are ready for the final release. Your versioning would look like this:

2.1.9-dev.1 – Your first pre-release version

2.1.9_dev.2 – Your second pre-release version

2.1.9_dev.3 – Your third pre-release version

2.1.9_dev.4 – Your fourth pre-release version

2.1.9 – Your release version

The pre-release tag and versioning lets you modify your release without incrementing the MAJOR, MINOR, or PATCH numbers. That way, your release version remains consistent while you work on your code, only incrementing the pre-release tag as you work.

Update your pre-release app version

To update your pre-release dev app version with the deprecated ocp app prepare command:

Update the version field in the app.yml file for your app on your local machine. Increment the pre-release dev version by 1 and save your changes. For example, if your current pre-release dev version is 0.0.0-dev.1, update it to 0.0.0-dev.2.

Run the following command in the OCP CLI to validate, package, upload, and build your pre-release dev app version:

ocp app prepare <path>

Publish your pre-release dev app version. In this example, <appVersion> is [email protected]:

ocp directory publish <appVersion>

Your app running in your personal OCP production account is automatically upgraded to the new app version. You can see this by navigating to the App Directory and clicking the app tile. The current version of your app displays:

General availability (GA) release versioning

When you are finished testing your app and are ready to release it to GA, you enter the app review process. Your app is approved as a beta app, private app, or released app:

Beta apps – Use the legacy -beta release tag with ocp app prepare to release your app as a beta. For apps that deploy with ocp app deploy, share a beta build on a beta/ preview track instead. Versions with a -beta suffix can only be installed using an app beta share link (for example, https://get.optimizely.app/{{app}}?v=1.0.0-beta).

Private apps – Apps that are released to production, but their availability in the OCP App Directory is limited to one or more accounts.

Released apps – Apps released to production are generally and publicly available in the OCP App Directory.

Update your GA app version

To release your app to production, promote the version your preview track runs to a semver version:

ocp app promote --from dev/USERNAME --to 1.0.0

To release your working directory instead, run ocp app deploy --version 1.0.0. Both commands build the release version with the release dependencies and start the app review process. After approval, rerun the command to publish the version, or add --watch to keep waiting for approval and publish when it arrives. You do not set the version in app.yml.

Your installations pinned to an earlier version of the same MAJOR version are upgraded automatically when the version is published.

Legacy: update your GA app version with ocp app prepare

Apps on a runtime earlier than node22 still release with the deprecated ocp app prepare command. To update the version and publish to production, complete the following steps:

Update the version field in the app.yml file for your app on your local machine. Remove the pre-release tag and save your changes. For example, if your current pre-release dev version is 0.0.0-dev.1, update it to 0.0.0.

Run the following command in the OCP CLI to validate, package, upload, and build your production app version:

ocp app prepare <path>

Publish your production app version. In this example, <appVersion> is [email protected]:

ocp directory publish <appVersion>

Your app running in your personal OCP production account is automatically upgraded to the new app version. You can see this by navigating to the App Directory and clicking the app tile.

Examples of valid app versions. Versions with a pre-release tag are valid only for the legacy ocp app prepare flow:

1.0.0
0.0.1-dev.1
1.0.0-beta.2
1.2.3-private

Example of invalid app versions:

Version	Reason
1.0	The version number only includes a MAJOR and MINOR number, but is missing the required PATCH number.
1.2.3.4	The version number includes four numbers separated by periods, which is not a valid semantic version.
1.002.3	The MINOR number has a leading zero.
1.2.3-dev.01	The pre-release tag has a leading zero.
1.2.3-internal	The pre-release tag is invalid; only dev, beta, and private are supported.
1.2.3-	The version number includes a hyphen followed by nothing, which is not a valid pre-release identifier.
1.2.3-beta-2	The pre-release version is followed by a hyphen instead of a dot.

Roll back a release

If a release breaks installations, move them back to an earlier release without building or reviewing a new version. A rollback is three commands. Each one shows what it will change and asks before changing anything. In this example, 1.3.0 is the bad release and 1.2.0 is the release to go back to.

This section applies to releases (semver versions). To roll back a preview track, run a single command, ocp app rollback, because the installations that follow a track move with it. For details, see Roll back a track.

Republish the earlier release:

ocp directory publish [email protected]

You can republish a release that you unpublished within the last seven days. OCP republishes it from its existing build, without a new review, in every availability region the app is available in. Republishing does not upgrade or downgrade any installation. After seven days the release's environment is removed, and the fix is a new release.

Move the installations off the bad release:

ocp directory upgrade my_app --allFromVersion 1.3.0 -v 1.2.0

The CLI checks every availability region the release is published to. Add -a <region> to limit the check to one region. The CLI lists every installation on 1.3.0 that you can access, per region, and asks you to confirm. It then moves the installations one at a time, region by region, and stops at the first failure. To continue with the installations still on 1.3.0, run the command again. Both versions must have the same MAJOR version. To move a single installation across a MAJOR version, run ocp directory upgrade my_app <trackerId> -v <version>. Each moved installation runs the upgrade lifecycle of 1.2.0, with fromVersion set to 1.3.0.

Unpublish the bad release if you no longer need it:

ocp directory unpublish [email protected]

Unpublishing is refused while any installation is still on the version, including installations in accounts you cannot access. It targets one availability region at a time (us by default), so run it once per region, for example ocp directory unpublish [email protected] -a eu. The report at the end of step 2 prints the command for each region where nothing is left on 1.3.0.

Republishing counts against the version limits like any other publish.

Version limits

OCP limits how many semver versions of an app run at the same time. The limits count running versions only. A version that is built but not started, or one that is stopped, does not count. Unpublish a version with ocp directory unpublish YOUR_APP_ID@VERSION to free its slot.

The following limits apply:

MAJOR versions per app – two

MINOR versions per MAJOR version – three

-dev versions per app (legacy) – five

-beta versions per app (legacy) – five

-private versions per app (legacy) – two

A publish that exceeds a limit fails with a message that names the limit, such as Deployment would exceed limit of 2 major versions for app my_app. Unpublish an unused version, then publish again.

Preview track versions do not count against these limits, and they have their own naming rules, including the 32-character version identifier. See Preview track limits.