Publish an app using release channels¶

This topic describes how to use release channels to manage and publish multiple versions of a Snowflake Native App.

About release channels¶

Release channels allow providers to publish apps at different stages of the app development lifecycle. For example, a provider can use release channels to perform the following tasks:

Test an app.
Publish an app to consumers as a preview or for UAT (user acceptance testing).
Publish the app to a production environment.

Providers enable release channels on the application package. Using release channels, a provider can create more than two versions of an app. The two-version limit applies to each release channel instead of per application package.

Supported release channels¶

The Snowflake Native App Framework supports the following release channels. The specific release channel a provider uses depends on the current stage of the app development lifecycle.

QA: Versions and patches of an app assigned to this release channel are only available to consumers within the provider’s organization. Apps published using this release channel must be targeted to a specific account within that organization.

Providers can use this release channel for testing. Apps published using the QA release channel are not required to run the automated security scan.
ALPHA: Versions and patches of an app assigned to this release channel can be published to consumers outside the provider’s organization. When an app is assigned to this release channel, the automated security scan is performed.

While the security scan is in progress, the provider can set the release directive for this version, and consumers can install it in their accounts. However, if a version assigned to this release channel fails the security scan, it can no longer be used.

Providers can use this channel to collaborate with consumers during the development of an app.
DEFAULT: Versions and patches of an app assigned to this release channel are available to all consumers who have access to the app version or patch. Apps assigned to this release channel must pass the automated security scan.

This release channel is the production release channel. All apps assigned to this release channel must conform to the security requirements and guidelines for publishing an app. For more information, see Security requirements and guidelines for a Snowflake Native App.

Privileges required to use release channels¶

To use release channels, you must use a role that has been granted the MANAGE RELEASES privilege. This privilege allows you to:

Enable release channels on the application package.
Enable the QA and ALPHA release channels.
Register and deregister versions and patches.
Add versions and patches.
Set the release directive.

Enable release channels for an application package¶

To use release channels to manage and publish an app, providers must enable release channels using the ENABLE_RELEASE_CHANNELS clause of the application package as shown in the following commands:

CREATE APPLICATION PACKAGE my_app_package ENABLE_RELEASE_CHANNELS=TRUE;
ALTER APPLICATION PACKAGE my_app_package SET ENABLE_RELEASE_CHANNELS=TRUE;

Copy

Warning

After release channels are enabled for an application package, they cannot be disabled.

Enable the ALPHA and QA release channels¶

By default, only the DEFAULT release channel is available to all consumers and enables them to install an app from a listing to which they have access.

To use the QA and ALPHA release channels providers must explicitly enable them on the application package for specific accounts. For these channels, the application package maintains a list of accounts that have been added to each channel.

Providers can add an account to a release channel using the MODIFY RELEASE CHANNEL clause of the ALTER APPLICATION command.

To add the ORG1.ACCOUNT1 account to the ALPHA release channel:

ALTER APPLICATION PACKAGE my_app_package MODIFY RELEASE CHANNEL ALPHA ADD ACCOUNTS=(ORG1.ACCOUNT1);

Copy

To remove the ORG1.ACCOUNT1 account from the ALPHA release channel:

ALTER APPLICATION PACKAGE my_app_package MODIFY RELEASE CHANNEL ALPHA REMOVE ACCOUNTS=(ORG1.ACCOUNT1);

Copy

To overwrite the current list of accounts added to a relase channel, a provider can use the SET clause of the ALTER APPLICATION PACKAGE command as shown in the following example:

ALTER APPLICATION PACKAGE my_app_package MODIFY RELEASE CHANNEL ALPHA SET ACCOUNTS=(ORG1.ACCOUNT2);

Copy

This command removes all current accounts from the ALPHA release channel and adds the ORG1.ACCOUNT2 account.

Monitoring release channels¶

View the release channels defined in an application package or listing¶

To view the release channels defined in the application package, use the SHOW RELEASE CHANNELS command as shown in the following example:

SHOW RELEASE CHANNELS IN APPLICATION PACKAGE my_app_package;

Copy

To view the release channels defined for a listing, use the SHOW RELEASE CHANNELS command as shown in the following example:

SHOW RELEASE CHANNELS IN LISTING <listing_id>;

Copy

View the release channel of an installed app¶

To view the release channels for all installed instances of an app, view the current_release_channel_name column of the SNOWFLAKE.DATA_SHARING_USAGE.APPLICATION_STATE view.

Manage versions and patches using release channels¶

Providers must add a version or patch to a specific release channel before they can be used by release directives inside a release channel. After a version has been added to a release channel, subsequent patches for that version are also bound to that release channel to be used.

Note

The ADD VERSION USING ‘@stage/path’ clause of the CREATE APPLICATION and ALTER APPLICATION PACKAGE commands is not supported for application packages that have release channels enabled. Providers must register and deregister a version with application package before creating the version.

Register a version¶

Before adding a new version of an app to an application package with release channels, providers must register the version in the release channel by using the REGISTER clause of the ALTER APPLICATION PACKAGE command:

ALTER APPLICATION PACKAGE my_app_package REGISTER VERSION V1 USING '@stage/path';

Copy

This command creates version V1 of the app and also creates patch 0. This version is not assigned to any release channel. There is a maximum of two unassigned versions (not added to any release channels) allowed in the application package.

Deregister a version¶

To create a new version in an application package that already has two versions, providers must deregister an old version.

To deregister a version and its associated patches, use the DEREGISTER clause of the ALTER APPLICATION PACKAGE. The following command shows how to deregister version v1 from the application package:

ALTER APPLICATION PACKAGE my_app_package DEREGISTER VERSION v1;

Copy

Note

When using release channels, you do not have to drop the existing version from the application package.

Add a version to a release channel¶

After registering a new version of an app in the application package, you must explicitly add the version to a release channel to set the release directive for the app.

To add a version to a release channel, use the ADD VERSION clause of the ALTER APPLICATION PACKAGE command:

ALTER APPLICATION PACKAGE my_app_package MODIFY RELEASE CHANNEL QA ADD VERSION V1;

Copy

Note

A release channel can only contain two simultaneous versions.

Remove a version from a release channel¶

To remove a version from a release channel, use the DROP clause of the ALTER APPLICATION PACKAGE:

ALTER APPLICATION PACKAGE my_app_package MODIFY RELEASE CHANNEL QA DROP VERSION V1;

Copy

Dropping a version from a release channel is asynchronous and will only be truly dropped once all consumers have been upgraded off that version.

Set the release directive using a release channel¶

When release channels are enabled for an application package, each channel has its own release directive.

To set the default release directive for a release channel:

ALTER APPLICATION PACKAGE my_app_package
  MODIFY RELEASE CHANNEL ALPHA
  SET DEFAULT RELEASE DIRECTIVE VERSION=v1 PATCH=10;

Copy

To set a custom release directive for a release channel:

ALTER APPLICATION PACKAGE my_app_package
  MODIFY RELEASE CHANNEL ALPHA
  SET RELEASE DIRECTIVE my_custom_release_directive
  VERSION=V1 PATCH=11 ACCOUNTS=(ORG1.ACCOUNT1);

Copy

Enable multiple instances using release channels¶

You can allow consumers to create multiple instances of an app in their account. Providers can also create multiple instances of an app in their test account.

To enable multiple instances use the MULTIPLE_INSTANCES property of the application package as shown in the following commands:

CREATE APPLICATION PACKAGE <name> MULTIPLE_INSTANCES=TRUE;
ALTER APPLICATION PACKAGE <name> SET MULTIPLE_INSTANCES=TRUE;

Copy

Note

Enabling multiple instances for the application package applies to all release channels within the application package.

Monetization and release channels¶

All app instances installed using the DEFAULT release channel use the pricing plan configured for the listing.

App instances installed from ALPHA and QA release channels are free and do not use the pricing plan configured for the listing.

Install an app using release channels¶

Providers can use CREATE APPLICATION to create an app from a release channel in their test environment.

Note

To install an app from the QA or ALPHA release channels, you must use a role that has been granted the CREATE PREVIEW APPLICATION privilege.

To install an app from an application package in the same account, run the following command:

CREATE APPLICATION my_app
  FROM APPLICATION PACKAGE my_app_package
  USING RELEASE CHANNEL QA;

Copy

If you do not explicitly use the USING RELEASE CHANNEL clause, the DEFAULT release channel is used.

To install an app in another account from a listing, run the following command:

CREATE APPLICATION my_app
  FROM LISTING
  USING RELEASE CHANNEL QA;

Copy

If you do not explicitly use the USING RELEASE CHANNEL clause, the DEFAULT release channel is used.