Release your app

16 min

When your app is ready, release a semantic version (semver) of it with ocp app promote or ocp app deploy --version. The release goes through review by Optimizely and is published to the OCP App Directory after approval.

For details on the legacy prepare, publish, and install flow, see Prepare, publish, and install.

Release options

When you release your app, choose one of the following options:

Normal version – A semver version without a pre-release tag, such as 1.0.0. The app is publicly available to all Optimizely customers in the App Directory after review approval.

Private version – Use the legacy -private tag with ocp app prepare, such as 1.0.0-private. ocp app deploy and ocp app promote do not accept -private versions. The app is released to production, but availability is limited to selected OCP accounts. Use this when you want to release production-ready functionality but control who can install the app. Private versions also require review approval. To install a private version to selected accounts, use the ocp directory install command:

ocp directory install [email protected] TRACKER_ID

To install the app on an instance, you need a role for that OCP instance. See Developer accounts and organizations for information on getting access and access levels.

Release with ocp app deploy

Note

ocp app deploy and ocp app promote require runtime: node22 or later in app.yml. Apps on earlier runtimes keep releasing with the deprecated ocp app prepare command until they migrate. See Validate, prepare, publish, and install.

If you develop on a preview track, the version on the track is not a release. The App Directory lists preview versions only for accounts that install or follow them.

To release a semantic version (semver), run the following command from your app directory:

ocp app deploy --version 1.0.0

Run ocp app validate first to check your app configuration. The command builds the release version from your working directory with the release dependencies and starts the app review process. It replaces setting the version in app.yml and running ocp app prepare and ocp directory publish. 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.

Alternatively, release the code a track already runs, instead of your working directory, by promoting the track to a semver version:

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

The promotion rebuilds the version the track runs with the release dependencies, starts the review, and publishes after approval in the same way.

See Release a semver version for details.

Validate, prepare, publish, and install

Legacy

ocp app prepare is deprecated. It still works, but prints the following warning: 'ocp app prepare' is deprecated. Deploy with ocp app deploy and release with ocp app promote --to <version>. Use these steps only for apps that set a version in app.yml, such as apps on a runtime earlier than node22. Without a version in app.yml, ocp app prepare fails.

Validate your app configuration by running ocp app validate in the CLI.

Run ocp app prepare to prepare your app for publishing. This initiates the code review process. When you run this command with a release version, the CLI prompts you to confirm:

You are uploading a release version of the app. This will start a review process and the app can't be published until it is approved. Are you sure?

Enter yes to proceed. When your app is approved (review takes one to two business days), proceed to step 3.

Publish the app to the OCP App Directory by running ocp directory publish [email protected]. See App versioning for details on versioning your app.

Run ocp directory install [email protected] TRACKER_ID to install the app into your OCP account. Replace TRACKER_ID with your OCP account tracker ID. For example, ocp directory install [email protected] Z6jCndly_E2WzpvDkcKBKA.

View your app listing in the OCP App Directory.

App review process

Note

The app review process typically takes one to two business days to complete.

Releasing a semver version with ocp app promote --to or ocp app deploy --version initiates the app review process. Running the deprecated ocp app prepare command with normal, beta, or private versions also initiates it.

The Optimizely App Review team invites you to a GitHub repository containing your app code. When you accept the invitation, you can see the pull request and feedback from Optimizely engineers as they review your code.

Note

GitHub notifies you by email about any activity in your app review repository.

If Optimizely determines that changes are required, Optimizely submits a GitHub pull request. After you make the requested changes, release the same version again with ocp app promote --to or ocp app deploy --version. Legacy apps use ocp app prepare instead. This updates the pull request with the latest code from your app.

This review ensures your app meets design guidelines, content guidelines, and security requirements so customers can safely use your app.

Best practices

Your app should meet the following guidelines before you submit it for review:

Security

Your app cannot contain any secrets or credentials. Store secrets in environment variables, in a .env file outside of GitHub.

Your app cannot log secrets or credentials.

The .env file cannot be part of the repository.

Your app cannot import PII data.

Your app cannot scan the engine code or invoke internal engine code other than through the API defined in the App SDK.

Your app cannot execute any OS commands directly.

Your app cannot gather, log, or send any information about how the runtime is built (OS version, folder structure, networking, ports, and so on).

app.yml

Your app must accurately identify itself in the metadata section. The app_id, display_name, and summary should clearly identify the app and its purpose.

All URLs you define in the metadata must be valid, functioning URLs.

Define the partner developing the app in the vendor field.

Jobs

The perform method should complete in under 60 seconds.

The prepare method should handle initializing and resuming the job.

Logging

Use logger for logging, not console.

src/schema

Prefix all objects and fields unique to your app with your app ID.

Storage

Your app cannot store data outside of OCP. Use available storage instead.

Only store secrets in the secrets store.

Track your app review in GitHub

When you submit your app for review, GitHub sends you an email inviting you to your app's repository in Optimizely-Connector-Platform-AppReview. Accept the invitation to participate in the review. GitHub notifies you each time Optimizely comments on your review or requests changes.

Communicate directly with the reviewers in GitHub throughout the review process.

Check review status in the OCP CLI

Run the following command in the OCP CLI to view your app's review status:

ocp directory status APP_REVIEW_ID@APP_VERSION

Open GitHub review from the OCP CLI

Run the following command in the OCP CLI to open the GitHub review in your browser:

ocp review open APP_REVIEW_ID@APP_VERSION

Change requests during app review

During the review, Optimizely may submit change requests through GitHub. To make the requested changes:

Make the requested changes, then run ocp app deploy to test them on your dev/USERNAME preview track.

Run the release command again with the same version, such as ocp app promote --from dev/USERNAME --to 0.0.1, to update the existing review.

Note

Maintain the same version number (for example, 0.0.1) throughout the review. Changing the version number creates a new review repository.

For apps that use the legacy ocp app prepare flow:

Change the version of your app in app.yml back to a dev version by adding the -dev tag. For example, if the app version you submitted for review was 0.0.1, change it to 0.0.1-dev.1.

Note

Maintain the same version number (for example, 0.0.1) throughout the review. Changing the version number creates a new review repository.

Make the requested changes, then test your app internally with the -dev tag.

Remove the -dev tag from the version in app.yml.

Run the following command in the OCP CLI to resubmit your app to the existing review:

ocp app prepare

Continue monitoring the review in GitHub and making the requested changes until your app is approved.

Release publicly

When Optimizely approves your app, rerun the release command, such as ocp app promote --from dev/USERNAME --to 1.0.0, to publish it. If you ran the command with --watch, it publishes the version when the approval arrives. For apps that use the legacy flow, or to publish a reviewed version directly, run the following command in the OCP CLI:

ocp directory publish [email protected]

Your app is then available in the OCP App Directory for all Optimizely customers.

Versioning after release

After your initial release, publish updates using the same versioning scheme:

PATCH versions like 1.0.1 – Bug fixes that require a review.

MINOR versions like 1.1.0 – Feature additions that auto-upgrade existing installations after review approval.

MAJOR versions like 2.0.0 – Breaking changes that require a review.

See App versioning for details on how OCP handles version upgrades and the legacy -dev workflow.