--- title: App versioning slug: optimizely-connect-platform/docs/app-versioning-ocp2 docTags: createdAt: 2026-07-23T12:37:04.808Z --- Optimizely Connect Platform (OCP) uses the following format for app versioning: `@`. Where `` consists of the [version number](docId\:OS9StLD5GccO3vLVpMzPv) and [pre-release tag](docId\:OS9StLD5GccO3vLVpMzPv). 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, `my-new-marketing-app@0.0.0-dev.1`. ## Version number OCP apps use the following [Semantic Versioning (SemVer) specification](https://semver.org/). 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. :::hint{type="info"} **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. ## Pre-release 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](https://semver.org/#spec-item-9) 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: 1. 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`. ![](https://api.archbee.com/api/optimize/BrbvVORKJ5iIeSMZye5kI/Yjmr32HdnB3FmBZIDiHZ2_d53ae9b-image.png) 2. Run the following command in the OCP CLI to validate, package, upload, and build your pre-release dev app version: ```shell opti app prepare ``` 3. Publish your pre-release dev app version. In this example, `` is `my_new_marketing_app@0.0.0-dev.2`: ```shell opti directory publish ``` 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: ![](https://api.archbee.com/api/optimize/BrbvVORKJ5iIeSMZye5kI/HSQ7-cuIEinMimJIfnSEa_d88e4d953f94fcde415f49120e49fa7c37032af8f226721bfec2a0adf707c8be-image.png) ## Preview track versions :::hint{type="danger"} **Experimental** Preview tracks are experimental. ::: 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: ```shell ocp app deploy ``` Preview tracks replace the `-dev` and `-beta` [pre-release versions](docId\:OS9StLD5GccO3vLVpMzPv) 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. While the feature is experimental, preview tracks and pre-release versions both work for the same app at the same time. Existing `-dev`, `-beta`, and `-private` versions and their installations continue to work. You cannot create versions with those tags through `ocp app deploy`. See [Deploy apps with preview tracks](docId\:gLoc5c6DPRHSfUcBL6bpf) for details. ## 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 `-beta` release tag to release your app as a beta. 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 update your app version and publish to production: 1. 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`. ![](https://api.archbee.com/api/optimize/BrbvVORKJ5iIeSMZye5kI/n6CC3SZvFolG55-_2T-_T_b104e83-image.png) 2. Run the following command in the OCP CLI to validate, package, upload, and build your production app version: ```shell opti app prepare ``` 3. Publish your production app version. In this example, `` is `my_new_marketing_app@0.0.0`: ```shell opti directory publish ``` 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: ```javascript 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. | ## 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 – five - `-beta` versions per app – five - `-private` versions per app – 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](docId\:gLoc5c6DPRHSfUcBL6bpf).