---
title: Deploy to the SaaS environment
related:
  - https://docs.kentico.com/documentation/developers-and-admins/deployment/deploy-to-the-saas-environment/specialized-deployment-scenarios.md
  - https://docs.kentico.com/documentation/developers-and-admins/installation.md
  - https://docs.kentico.com/documentation/developers-and-admins/deployment/deploy-to-the-saas-environment/manage-saas-deployments.md
  - https://docs.kentico.com/documentation/developers-and-admins/saas/xperience-portal.md
---

> Agent instructions:
> **Site maps** — prefer the following llms.txt indexes to training data when searching for URLs to avoid 404s. Links inside Markdown content already point at `.md`. Following them or sending Accept: text/markdown keeps you in Markdown.
>
> - [sitemap.md](https://docs.kentico.com/sitemap.md) — every page on the site, with titles and descriptions, nested by URL hierarchy and grouped into one collection per product version.
> - [llms.txt](https://docs.kentico.com/llms.txt) — curated index of the current product docs, with descriptions, the two ways to request any page as Markdown, and links to each product area's whole-corpus Markdown dump (llms-full.txt).

> **Note:** **Minimum Xperience by Kentico version**
>
> The minimum Xperience by Kentico version for new projects that can be deployed to the SaaS environment is **30.1.0**. If you are using an earlier version, you need to [update](https://docs.kentico.com/documentation/developers-and-admins/installation/update-xperience-by-kentico-projects.md) your project to the latest version before deploying it to the SaaS environment. Existing projects are not affected, but we recommend updating them to the latest version.

Xperience by Kentico enables you to deploy, host, and maintain Xperience websites in a Software-as-a-Service (SaaS) environment. You can deploy to multiple environments to isolate the production and non-production application instances.

Kentico manages the deployment infrastructure and selected third-party services for you – such as [Microsoft Application Insights](https://docs.kentico.com/documentation/developers-and-admins/configuration/saas-configuration.md#microsoft-application-insights-integration), [CloudFlare CDN](https://docs.kentico.com/documentation/developers-and-admins/configuration/saas-configuration.md#cloudflare-cdn), and [Twilio SendGrid](https://docs.kentico.com/documentation/developers-and-admins/configuration/email-configuration.md#emailconfiguration-enablemanagedsendgrid). This allows you to focus on website and content development.

Develop a website for deployment to the SaaS environment:

1. [Get access to your project in Xperience Portal](https://docs.kentico.com/documentation/developers-and-admins/saas/xperience-portal.md#xperienceportal-accessportal).
2. [Prepare a .NET project for deployment to the SaaS environment](#prepare-a-project-for-deployment-to-the-saas-environment).
3. [Develop](https://docs.kentico.com/documentation/developers-and-admins/development.md) and [configure](https://docs.kentico.com/documentation/developers-and-admins/configuration.md) features in your project.
4. [Deploy](#deploytothesaasenvironment-deploy) your application to the SaaS environment.
5. [Manage](https://docs.kentico.com/documentation/developers-and-admins/deployment/deploy-to-the-saas-environment/manage-saas-deployments.md) your deployed application in Xperience Portal.

![Overview of the SaaS deployment](https://docs.kentico.com/docsassets/documentation/deploy-to-the-saas-environment/saas_deployment_diagram.png "Overview of the SaaS deployment")

## Prepare a project for deployment to the SaaS environment

You can now prepare a .NET project for deployment to the SaaS environment.

1. [Install the Xperience project templates](https://docs.kentico.com/documentation/developers-and-admins/installation.md#install-project-templates-package).
2. [Create an Xperience project](https://docs.kentico.com/documentation/developers-and-admins/installation.md#create-a-project).
   - Use the `--cloud` parameter when [creating the Xperience project](https://docs.kentico.com/documentation/developers-and-admins/installation.md#create-a-project). This parameter ensures the necessary configuration is included:
     - The [Kentico.Xperience.Cloud](https://www.nuget.org/packages/Kentico.Xperience.Cloud) NuGet package
     - [SendGrid](https://docs.kentico.com/documentation/developers-and-admins/configuration/email-configuration.md#managed-sendgrid-integration) and  [Microsoft Application Insights](https://docs.kentico.com/documentation/developers-and-admins/configuration/saas-configuration.md#deploytothesaasenvironment-enableappinsights) startup configurations
     - A PowerShell script for [generating the deployment package](https://docs.kentico.com/documentation/developers-and-admins/deployment/deploy-to-the-saas-environment.md#create-a-deployment-package) and a [CD configuration file](https://docs.kentico.com/documentation/developers-and-admins/ci-cd/continuous-deployment.md#generate-cd-configuration-files)
     - [Storage path mapping](https://docs.kentico.com/documentation/developers-and-admins/api/files-api-and-cms-io/file-system-providers/storage-path-mapping.md) configured in `Program.cs` (for [mapping of files to Azure Blob storage](https://docs.kentico.com/documentation/developers-and-admins/api/files-api-and-cms-io/file-system-providers/azure-blob-storage.md#default-kentico-managed-azure-blob-storage-configuration))
3. [Create the project database](https://docs.kentico.com/documentation/developers-and-admins/installation.md#create-the-project-database).
   - Generate [a developer license key](https://docs.kentico.com/documentation/developers-and-admins/installation/licenses.md#license-keys-for-saas-local-development).
   - Set the value of the `--hash-string-salt` parameter to the one found on the [Xperience Portal Dashboard](https://docs.kentico.com/documentation/developers-and-admins/saas/xperience-portal.md#hash-string-salt-for-the-xperience-portal-project).
4. Include the `UseKenticoCloud` component in the [project's middleware pipeline](https://docs.kentico.com/documentation/developers-and-admins/development/website-development-basics/configure-new-projects.md#configure-application-startup).
   - Use the `.IsQa()` and `.IsUat()` [extension methods](https://docs.kentico.com/documentation/developers-and-admins/configuration/saas-configuration.md#environment-identification-extension-methods) to include environment-specific configuration or code
   - [Call](https://docs.kentico.com/documentation/developers-and-admins/configuration/saas-configuration.md#microsoft-application-insights-integration) `AddXperienceCloudApplicationInsights` when building the web application
   - Configure cache headers for [Cloudflare CDN](https://docs.kentico.com/documentation/developers-and-admins/configuration/saas-configuration.md#cloudflare-cdn)
5. Build the project. Run the following command from the project's root directory or build the project using Visual Studio.

   ```cmd
   dotnet build
   ```

The project is now ready for further [development](https://docs.kentico.com/documentation/developers-and-admins/development.md) and [customization](https://docs.kentico.com/documentation/developers-and-admins/customization.md). You can add content to the project or [extend](https://docs.kentico.com/documentation/developers-and-admins/customization/extend-the-administration-interface.md) the connected Xperience administration. The following code example demonstrates the required SaaS configuration. Ellipsis indicates breaks where other middleware may be added:

```csharp title="Program.cs - SaaS configuration"
using Kentico.Web.Mvc;
using Kentico.Xperience.Cloud;

using Microsoft.Extensions.Hosting;
using Microsoft.AspNetCore.Builder;
using Microsoft.Extensions.DependencyInjection;

var builder = WebApplication.CreateBuilder(args);

// Required for projects that will be deployed to the SaaS environment
builder.Services.AddXperienceCloudStoragePathMapping();
builder.Services.AddXperienceCloudApplicationInsights(builder.Configuration);
builder.Services.AddXperienceCloudChannelRequirements();

// Required for projects that will be deployed to the SaaS environment
if (builder.Environment.IsQa()
    || builder.Environment.IsUat()
    || builder.Environment.IsEnvironment(CloudEnvironments.Custom)
    || builder.Environment.IsEnvironment(CloudEnvironments.Staging)
    || builder.Environment.IsProduction())
{
    builder.Services.AddKenticoCloud(builder.Configuration);
    builder.Services.AddXperienceCloudSendGrid(builder.Configuration);
    builder.Services.AddXperienceCloudDataProtection(builder.Configuration);
}

builder.Services.AddKentico();
builder.Services.AddAuthentication();
builder.Services.AddControllersWithViews();

...

app.UseAuthentication();

// SaaS-specific middleware (required for SaaS deployment)
app.UseKenticoCloud();

app.UseKentico();

...

// Starts the application
app.Run();
```

## Deploy to the SaaS environment

When your Xperience project is [prepared](#prepare-a-project-for-deployment-to-the-saas-environment) and [configured](https://docs.kentico.com/documentation/developers-and-admins/configuration/saas-configuration.md) in a local development environment, you can deploy the application to the SaaS environment. Choose the appropriate deployment method for your scenario:

- **Initial deployments**: Deploy to the SaaS environment with a [deployment package](#deploy-with-a-deployment-package). If your project includes a large amount of assets or other data, use [custom restore](https://docs.kentico.com/documentation/developers-and-admins/deployment/deploy-to-the-saas-environment/specialized-deployment-scenarios.md#deploy-a-large-amount-of-data-during-initial-deployments) to deploy this data.

- **Regular content updates**: Use [content sync](https://docs.kentico.com/documentation/business-users/content-sync.md) to deploy updates for [supported](https://docs.kentico.com/documentation/business-users/content-sync.md#supported-content) types of content (_Advanced_ license required). See [Content sync configuration](https://docs.kentico.com/documentation/developers-and-admins/configuration/content-sync-configuration.md) for configuration details. If the updated content is not supported by content sync or if the feature is not available, deploy the changes via a new [deployment package](#deploy-with-a-deployment-package).

- **Application updates**: Use the [deployment package](#deploy-with-a-deployment-package) when [updating](https://docs.kentico.com/documentation/developers-and-admins/installation/update-xperience-by-kentico-projects.md) to a new version of Xperience by Kentico or when deploying new [custom features](https://docs.kentico.com/documentation/developers-and-admins/customization.md). Changing application files is only possible through this type of deployment.

### Deployment type overview

When planning a deployment, consider how it affects application availability. After you deploy, you can verify the **deployment type** in **Deployment history** to see which of the three types was used:

- **Live** – Your application remains fully operational throughout the deployment. Occurs when you deploy without database or storage changes.
- **Offline** – Your application goes offline and displays a static page during deployment. Occurs when you deploy with database or storage changes. [Customize the offline page](https://docs.kentico.com/documentation/developers-and-admins/configuration/saas-configuration.md#define-a-custom-app-offline-file) to match your brand during the downtime.
- **Zero-downtime** – Your application enters [read-only mode](https://docs.kentico.com/documentation/developers-and-admins/deployment/read-only-deployments.md) during deployment. Occurs when you deploy with database or storage changes and [zero-downtime](#zero-downtime-deployments) enabled.

## Deploy with a deployment package

Deploying to the SaaS environment with a deployment package allows you to deploy all parts of your SaaS project (application binaries, selected database data and storage assets). To deploy using this method, [create a deployment package](#create-a-deployment-package) and [ upload it to your Xperience Portal project](#upload-a-deployment-package-to-your-xperience-portal-project).

> **Info:** Deployment packages do not create an exact copy of your local project in the target environment because they contain only the database objects included in your [CD repository](https://docs.kentico.com/documentation/developers-and-admins/ci-cd/continuous-deployment.md). See [Deployment overview](#deployment-overview) and [Create a deployment package](#create-a-deployment-package) for details.

### Deployment overview

The following steps provide an overview of the entire lifecycle of a deployment:

1. You [install](https://docs.kentico.com/documentation/developers-and-admins/installation.md), [configure](https://docs.kentico.com/documentation/developers-and-admins/configuration/saas-configuration.md) and [develop](https://docs.kentico.com/documentation/developers-and-admins/development.md) an Xperience project from a [template](https://docs.kentico.com/documentation/developers-and-admins/installation.md#available-project-templates). A project installed with the `--cloud` option contains the following:
   - An Xperience .NET application.
   - Adjustments for SaaS deployment in the application's service collection and middleware pipeline within the **Program.cs** file.
   - A configuration file for the [Continuous Deployment (CD)](https://docs.kentico.com/documentation/developers-and-admins/ci-cd/continuous-deployment.md) repository, used to deploy database objects.
   - The **Export-DeploymentPackage.ps1** PowerShell script that creates a deployment package for the project.
   - [Storage path mapping](https://docs.kentico.com/documentation/developers-and-admins/api/files-api-and-cms-io/file-system-providers/storage-path-mapping.md) configured in `Program.cs` that maps folders containing physical files such as [content item assets](https://docs.kentico.com/documentation/business-users/content-hub/content-item-assets.md) and binary files to Azure Blob storage and local storage for development. See [Azure Blob storage](https://docs.kentico.com/documentation/developers-and-admins/api/files-api-and-cms-io/file-system-providers/azure-blob-storage.md).
2. You [create a deployment package](#create-a-deployment-package) from the project. A deployment package is a ZIP archive that contains the following:
   - Application libraries and static files.
   - `$CDRepository` folder containing serialized database objects.
   - A specified [CD configuration](https://docs.kentico.com/documentation/developers-and-admins/ci-cd/continuous-deployment.md).
   - (_Optional_) `$StorageAssets` folder for physical files.
3. When you [upload](#upload-a-deployment-package-to-your-xperience-portal-project) the deployment package to the SaaS environment, it is restored in the QA environment according to the specified [CD configuration](https://docs.kentico.com/documentation/developers-and-admins/ci-cd/continuous-deployment.md).
4. When you [deploy the package to another environment](#deploy-the-package-to-another-deployment-environment), the same deployment package is applied to the selected environment and restored according to the [CD configuration](https://docs.kentico.com/documentation/developers-and-admins/ci-cd/continuous-deployment.md).
   - Changes in the administration interface done during testing on the previous environment will not be reflected in other environments.
   - Databases of different environments are completely independent and never copied between environments. They are only updated by new deployments or users performing action in the administration interface.
5. When deploying a package to the production environment, the same deployment package is applied and restored according to the [CD configuration](https://docs.kentico.com/documentation/developers-and-admins/ci-cd/continuous-deployment.md).
   - See [Deploy data to the production environment](#deploy-data-to-the-production-environment) to learn how to upload content to the production environment.

After deploying to each environment, the SaaS infrastructure performs a slot swap to replace the currently running application with the newly deployed version. The swap includes a [status validation check](#swap-status-validation) to verify that the application started correctly.

> **Note:** **Notes**
>
> - Currently, the **maximum size of the deployment package is 2 GB**. Some binary files, such as content item assets, are bundled in the deployment package. If you need to deploy more data during initial deployments (e.g., when [upgrading](https://docs.kentico.com/documentation/developers-and-admins/upgrade-to-xperience-by-kentico.md) to Xperience by Kentico), use [custom restore](https://docs.kentico.com/documentation/developers-and-admins/deployment/deploy-to-the-saas-environment/specialized-deployment-scenarios.md#deploy-a-large-amount-of-data-during-initial-deployments).
> - It is essential to consider what [CD configuration](https://docs.kentico.com/documentation/developers-and-admins/ci-cd/continuous-deployment.md) to be used with each deployment package. You can [exclude objects](https://docs.kentico.com/documentation/developers-and-admins/ci-cd/configure-ci-cd-repositories.md) from the CD repository to limit what objects are restored in the SaaS environment. You can also specify a [CD restore mode](https://docs.kentico.com/documentation/developers-and-admins/ci-cd/continuous-deployment.md#cdrestoremode) used to restore the CD repository.
> - When deploying to a SaaS environment containing an existing deployment, the Xperience version that you deploy **cannot be lower** than the version in the target environment. You can only deploy the same or newer version.
> - Non-production environments (_QA_, _UAT_ or custom) only serve to test the functionality of your project. Any data or content edited in these environments **will not** be transferred during deployment to the _Production_ environment.
> - After promoting a build to the _Production_ environment, production data can be added. Use [workflows](https://docs.kentico.com/documentation/developers-and-admins/configuration/workflows.md) to prevent incomplete data from appearing publicly.
> - Only the latest deployed package can be promoted to the next environment.

### Create a deployment package

A deployment package is a ZIP archive with application libraries and static files, and a _$CDRepository_ folder with serialized database objects, and optionally a _$StorageAssets_ folder for physical files.

Follow the procedure to build your application and create a deployment package:

1. Use [Continuous Deployment](https://docs.kentico.com/documentation/developers-and-admins/ci-cd/continuous-deployment.md) to serialize database objects to the file system:

   1. Edit the **$CDRepository/repository.config** file according to your object filtering and deployment requirements. See [Exclude objects from CI/CD](https://docs.kentico.com/documentation/developers-and-admins/ci-cd/configure-ci-cd-repositories.md).

      > **Info:** You cannot adjust the location of the Continuous Deployment repository. The deployment process expects the _$CDRepository_ folder to be in the project root.
   2. Prepare [migration scripts](https://docs.kentico.com/documentation/developers-and-admins/ci-cd/ci-cd-database-migration-scripts.md) for any database changes not covered by Continuous Deployment.

      > **Tip:** **Run SQL scripts on the database**\
      > You can use [CD migration scripts](https://docs.kentico.com/documentation/developers-and-admins/ci-cd/ci-cd-database-migration-scripts.md) to perform SQL queries on the database of applications deployed in [SaaS environments](#deploy-the-package-to-another-deployment-environment), for example, to fix database inconsistencies. However, remember to always [create a restore point](https://docs.kentico.com/documentation/developers-and-admins/deployment/deploy-to-the-saas-environment/manage-saas-deployments.md#create-a-manual-restore-point) before modifying the database.
   3. Run the CD store command from the project's root directory:

      ```powershell
      dotnet run --no-build -- --kxp-cd-store --repository-path ".\$CDRepository"
      ```

      > **Tip:** **Escaping the '$' character**
      >
      > When performing this action in certain command line interfaces (e.g., PowerShell running on MacOS and the default Windows Terminal), you need to escape the dollar sign (`$`) by prefixing it with the grave accent (`` ` ``).
2. Deploy any unmanaged binary files that are not part of the `$StorageAssets` directory directly to [Azure Blob storage](https://docs.kentico.com/documentation/developers-and-admins/api/files-api-and-cms-io/file-system-providers/azure-blob-storage.md), as the **Export-DeploymentPackage.ps1** script will not include them in the deployment package.

   > **Tip:** **Copying files to Azure Blob storage**
   >
   > You can use tools like [Azure Storage Explorer](https://learn.microsoft.com/en-us/azure/storage/storage-explorer/vs-azure-tools-storage-manage-with-storage-explorer) and [AzCopy](https://learn.microsoft.com/en-us/azure/storage/common/storage-use-azcopy-blobs-copy) to _directly copy files to the Azure storage container_.
   >
   > Azure Storage Explorer works for manual operations, while AzCopy is a command line utility that you can use on an ad-hoc basis or in pipelines and scripts. If your development environment is hosted in Azure and deployed through an Azure DevOps pipeline, you can use the [Azure file copy](https://learn.microsoft.com/en-us/azure/devops/pipelines/tasks/reference/azure-file-copy-v6?view=azure-pipelines) task.
3. Create the deployment package with the **Export-DeploymentPackage.ps1** script.

   > **Info:** On Windows environments, the executing account must have permissions to run PowerShell scripts from external sources:
   >
   > ```powershell
   > # Bypass all execution checks for the current user
   > Set-ExecutionPolicy Bypass -Scope CurrentUser -Force
   > ```
   >
   > See [Set-ExecutionPolicy](https://learn.microsoft.com/en-us/powershell/module/microsoft.powershell.security/set-executionpolicy) for other types of permission levels.

   - Refer to the list of parameters before running the script.

     ```powershell
     .\Export-DeploymentPackage.ps1 -AssemblyName "DancingGoat"
     ```

     - `-AssemblyName` – the name of the main web application assembly used during project publishing.
       - The value **must be equal** to the [assembly name](https://docs.microsoft.com/en-us/dotnet/api/system.reflection.assemblyname?view=net-6.0) of the Xperience project (by default, the assembly name is equal to the project _.csproj_ file name without an extension).
     - _(Optional)_ `-OutputPackagePath` – the full path where the deployment package will be exported. Must include the package file name and extension.

       - For example, `./DeploymentPackage.zip`.
       - When omitted, the deployment package **DeploymentPackage.zip** is exported to the directory from which the script was executed.
     - _(Optional)_ `-KeepProductVersion` – by default, the deployment package is created with a **Build number** equal to the source project's package version, suffixed with the export date and time in format '_yyyyMMddHHmm_'.

       - Add this parameter if you wish to exclude the date and time from the **Build number**.
       - The **Build number** is displayed in the **Deployment history** within Xperience Portal.
     - _(Optional)_ `-StorageAssetsDeploymentMode [-Create] [-CreateUpdate]` – determines whether the export preserves or overwrites the storage assets already present in [Azure Blob storage](https://docs.kentico.com/documentation/developers-and-admins/api/files-api-and-cms-io/file-system-providers/azure-blob-storage.md):

       - When omitted, the `-Create` mode is used, and existing storage assets will not be overwritten and only new assets are added.
       - Use the `-CreateUpdate` parameter to allow overwriting of existing storage assets.

         > **Note:** If your deployment package contains [media library files](https://docs.kentico.com/documentation/business-users/media-libraries/manage-media-files.md), the `StorageAssetsDeploymentMode` value must match the `RestoreMode` element value in the CD configuration file. See [Reference - CI/CD object types](https://docs.kentico.com/documentation/developers-and-admins/ci-cd/reference-ci-cd-object-types.md#content-management).
     - _(Optional)_ `-ZeroDowntimeSupportEnabled` – marks the deployment package as zero-downtime ready. Include this parameter if your application code supports [read-only mode](https://docs.kentico.com/documentation/developers-and-admins/deployment/read-only-deployments.md). When a zero-downtime ready package is deployed to an environment that already contains code configured to support read-only mode, the deployment will be executed as a [zero-downtime deployment](#zero-downtime-deployments).

The deployment package is now created, and you can deploy to the SaaS environment by [uploading the deployment package to your Xperience Portal project](#upload-a-deployment-package-to-your-xperience-portal-project).

### Upload a deployment package to your Xperience Portal project

Once you have [created a deployment package](#create-a-deployment-package), trigger the deployment to the **QA** environment by uploading a deployment package to your Xperience Portal project directly from [Xperience Portal](#upload-a-deployment-package-from-xperience-portal) or programmatically using [Xperience Portal API](#upload-a-deployment-package-using-xperience-portal-api).

> **Info:** Uploading a deployment package to Xperience Portal is unavailable during [scheduled Xperience Portal project maintenance](https://docs.kentico.com/documentation/developers-and-admins/saas/xperience-portal.md#schedule-maintenance-of-xperience-portal-projects) and initial project creation.

> **Note:** The deployment package is currently limited by a **maximum size of 2 GB**. If you need to deploy more data during initial deployments (e.g., when [upgrading](https://docs.kentico.com/documentation/developers-and-admins/upgrade-to-xperience-by-kentico.md) to Xperience by Kentico), use [custom restore](https://docs.kentico.com/documentation/developers-and-admins/deployment/deploy-to-the-saas-environment/specialized-deployment-scenarios.md#deploy-a-large-amount-of-data-during-initial-deployments).

#### Upload a deployment package from Xperience Portal

1. [Access your Xperience Portal project](https://docs.kentico.com/documentation/developers-and-admins/saas/xperience-portal.md#xperienceportal-accessportal).
2. Navigate to the **Deployments** application.
3. Under the **QA** environment, select **Upload package**.
   - Users in **DevOps Engineer** or **Tenant Administrator** [roles](https://docs.kentico.com/documentation/developers-and-admins/saas/xperience-portal/reference-xperience-portal-user-roles.md) can also upload deployment packages directly to other non-production environments, or even directly to the _PROD_ environment in extraordinary circumstances. See [Specialized SaaS deployment scenarios](https://docs.kentico.com/documentation/developers-and-admins/deployment/deploy-to-the-saas-environment/specialized-deployment-scenarios.md#deploy-emergency-fixes-to-the-saas-environment).
4. Choose a valid deployment package (a ZIP archive with a maximum size of 2 GB) and select **Upload**. You will be redirected to the **Deployments** application after the upload is complete.
5. The progress of any current deployments can be tracked in the **Deployment progress** section, where you can check the status of the deployment. After the deployment is completed, you can review it in the **Deployment history** section.

After the deployment finishes, your site is ready and running in the **QA** (or another selected) environment. Access the deployed application with the URL displayed under the selected environment section in the **Deployments** application in your Xperience Portal project.

To debug the deployment, you can download an archive with **deployment logs** under the **Deployment history** section.

#### Upload a deployment package using Xperience Portal API

You can upload the deployment package programmatically by sending a POST request authenticated with your [Personal access token (PAT)](https://docs.kentico.com/documentation/developers-and-admins/saas/xperience-portal.md#xperienceportal-pat) to the _deployment_ Xperience Portal API endpoint:

1. Generate a [Personal access token (PAT)](https://docs.kentico.com/documentation/developers-and-admins/saas/xperience-portal.md#xperienceportal-pat) and store it in a local file.
2. Get your `PROJECT_GUID` in [Xperience Portal](https://docs.kentico.com/documentation/developers-and-admins/saas/xperience-portal.md) Dashboard, in the **Project info** section, or from any URL when accessing Xperience Portal, for example, _https://xperience-portal.com//dashboard_.
3. Send a POST request to the _deployment_ API endpoint. You can use the following PowerShell or cURL examples:

   ```powershell title="Upload using PowerShell"
   # Due to a PowerShell issue, we recommended disabling the progress bar to boost the performance significantly. 
   # See https://github.com/PowerShell/PowerShell/issues/2138 for more information.
   # Disable the progress bar
   $ProgressPreference = 'SilentlyContinue'

   # Upload the deployment package
   $headers = @{ Authorization = "Bearer <PERSONAL_ACCESS_TOKEN>" }
   Invoke-RestMethod -Uri https://xperience-portal.com/api/deployment/upload/<PROJECT_GUID>/qa -Method Post -InFile <FILE_PATH> -ContentType "application/zip" -Headers $headers

   # Enable the progress bar
   $ProgressPreference = 'Continue'
   ```

   ```powershell title="Upload using cURL"
   curl -X POST -T <FILE_PATH> -H 'Content-Type: application/zip' -H 'Authorization: Bearer <PERSONAL_ACCESS_TOKEN>' https://xperience-portal.com/api/deployment/upload/<PROJECT_GUID>/qa
   ```

   - Users in **DevOps Engineer** or **Tenant Administrator** [roles](https://docs.kentico.com/documentation/developers-and-admins/saas/xperience-portal/reference-xperience-portal-user-roles.md) can also upload deployment packages directly to other non-production environments, or even directly to the _PROD_ environment in extraordinary circumstances. See [Specialized SaaS deployment scenarios](https://docs.kentico.com/documentation/developers-and-admins/deployment/deploy-to-the-saas-environment/specialized-deployment-scenarios.md#deploy-emergency-fixes-to-the-saas-environment).
4. Navigate to the **Deployments** application.
5. Allow a few minutes for the deployment progress to be displayed in the **Deployment history** section, where you can check the deployment progress.

After the deployment finishes, your site is ready and running in the **QA** environment. Access the deployed application with the URL displayed under the **QA** environment section in the **Deployments** application in your Xperience Portal project.

To debug the deployment, you can download an archive with **deployment logs** under the **Deployment history** section.

### Deploy data to the production environment

Keep the following in mind when performing standard deployments to production:

- Deployment packages are intended for deploying the project only with initial data and content:
  - Website/email/headless channels, content types representing the content model, page tree structure, basic emails, essential content items
  - Assets that are essential for the design and branding, such as a favicon, background images, graphics, icons, and company logos
- Large binary files should be uploaded directly to the production environment:
  - All marketing assets, images, videos, large documents
- If your deployment package would exceed 2 GB during initial deployments, use [custom restore](https://docs.kentico.com/documentation/developers-and-admins/deployment/deploy-to-the-saas-environment/specialized-deployment-scenarios.md#deploy-a-large-amount-of-data-during-initial-deployments) to deploy the database and [storage](https://docs.kentico.com/documentation/developers-and-admins/api/files-api-and-cms-io/file-system-providers/azure-blob-storage.md) assets.
- If you use Xperience by Kentico to manage content imported from external sources, it is recommended to import the content directly to the production or staging environment.

The [Content sync](https://docs.kentico.com/documentation/developers-and-admins/configuration/content-sync-configuration.md) feature allows you to set up content staging for SaaS environments. See [Content staging best practices](https://docs.kentico.com/documentation/developers-and-admins/configuration/content-sync-configuration.md#content-staging-best-practices) to learn which environments are suitable for staging.

### Zero-downtime deployments

Zero-downtime deployments update your live site without service interruptions. SaaS deployments use Kentico-managed infrastructure (deployment slots, database replication, blob versioning) that automatically switches your application to [read-only mode](https://docs.kentico.com/documentation/developers-and-admins/deployment/read-only-deployments.md) to maintain data consistency.

> **Info:** Zero-downtime deployments require version of Xperience by Kentico 31.0.2 or higher, an updated infrastructure and [read-only mode](https://docs.kentico.com/documentation/developers-and-admins/deployment/read-only-deployments.md) support in your application code. Your application must be configured to handle read-only mode before zero-downtime deployments can be used. Without proper read-only mode implementation, zero-downtime deployments will not function correctly.
>
> See [Read-only deployments](https://docs.kentico.com/documentation/developers-and-admins/deployment/read-only-deployments.md) for detailed information about read-only mode behavior, required code changes, and disabled functionality.

To enable zero-downtime deployments for your project:

1. Update your **Export-DeploymentPackage.ps1** script to the latest version that includes the `-ZeroDowntimeSupportEnabled` parameter. If your project was created before this feature was available, replace your existing script with the latest version: [Export-DeploymentPackage.ps1](https://docs.kentico.com/docsassets/documentation/deploy-to-the-saas-environment/Export-DeploymentPackage.ps1).
2. Configure your application code to support [read-only mode](https://docs.kentico.com/documentation/developers-and-admins/deployment/read-only-deployments.md). This is a mandatory prerequisite. Your code must:

   - Prevent custom write operations when read-only mode is active (check [required project changes](https://docs.kentico.com/documentation/developers-and-admins/deployment/read-only-deployments.md#required-project-changes) for details)
   - Handle [disabled functionality](https://docs.kentico.com/documentation/developers-and-admins/deployment/read-only-deployments.md#disabled-functionality) during read-only mode (forms, activity tracking, contact management, etc.)

   See [Read-only deployments](https://docs.kentico.com/documentation/developers-and-admins/deployment/read-only-deployments.md) for complete implementation instructions.
3. Mark your deployment package as zero-downtime ready when [creating the deployment package](#create-a-deployment-package) using the **Export-DeploymentPackage.ps1** script with the `-ZeroDowntimeSupportEnabled` parameter.
4. Deploy the package to an environment. Once an environment contains code supporting zero-downtime deployments, all subsequent deployments of packages marked as zero-downtime ready will be executed as zero-downtime deployments.

Your project is now configured for zero-downtime deployments. When you deploy packages marked with the `-ZeroDowntimeSupportEnabled` parameter to an environment containing zero-downtime ready code, the SaaS infrastructure automatically executes the deployment in read-only mode, eliminating service interruptions during updates.

> **Note:** **Notes**
>
> - The first deployment with the `-ZeroDowntimeSupportEnabled` flag enables zero-downtime infrastructure but uses standard deployment. Only subsequent deployments with the flag will be zero-downtime.
> - When you deploy a package without the `-ZeroDowntimeSupportEnabled` flag to an environment with existing zero-downtime ready code, the feature is disabled and standard deployment is used. Subsequent deployments without the flag will also use standard deployment.
> - For [private cloud](https://docs.kentico.com/documentation/developers-and-admins/deployment/deploy-to-private-cloud.md) deployments, see [Read-only deployments](https://docs.kentico.com/documentation/developers-and-admins/deployment/read-only-deployments.md) for manual infrastructure setup and deployment process.

### Swap status validation

As the final step of the deployment, the SaaS infrastructure performs a slot swap to replace the currently running application with the newly deployed version. During the swap, the deployment process sends a warmup request to the application and checks that it responds with one of the following allowed HTTP status codes:

















If the application returns a different status code (for example due to a startup error or a middleware that returns an unsupported status), the swap fails and the entire deployment is marked as failed.

> **Note:** If your application uses IP-based access restrictions (e.g., firewall rules, IP allowlists, or similar mechanisms), make sure that blocked requests return one of the allowed status codes listed above (typically **401** or **403**). If blocked requests return a different status code (e.g., **429** or **503**), the warmup check treats the application as broken and the deployment fails.

## Deploy the package to another deployment environment

The following SaaS **deployment environments** are available, depending on your [service plan](https://docs.kentico.com/documentation/developers-and-admins/saas/saas-service-plans.md):

- **QA** – A QA engineer tests the deployed application in the QA environment and deploys the deployment package to the UAT ([User Acceptance Testing](https://en.wikipedia.org/wiki/Acceptance_testing#User_acceptance_testing)) environment, if available.
- **UAT** – A project manager tests the final functionality in the UAT environment and promotes the deployment package to the production (PROD) environment.
  > **Info:** The UAT environment is only available for **Custom** [service plans](https://docs.kentico.com/documentation/developers-and-admins/saas/saas-service-plans.md).
- **STG** – An environment where editors and other staff can prepare content, and then transfer it to the production (PROD) environment using [content sync](https://docs.kentico.com/documentation/business-users/content-sync.md). Staging environments are designed to be nearly identical to production environments in most aspects, such as performance, availability, backup policies, and the option to set custom domains. See [Content staging best practices](https://docs.kentico.com/documentation/developers-and-admins/configuration/content-sync-configuration.md#content-staging-best-practices).
  > **Info:** The STG environment can optionally be purchased for any [service plan](https://docs.kentico.com/documentation/developers-and-admins/saas/saas-service-plans.md).
- **PROD** – A live production environment. Use this environment to deploy a tested iteration of your application.

After [deploying a deployment package](#deploy-with-a-deployment-package) to the QA environment, you can deploy it to another environment in [Xperience Portal](https://docs.kentico.com/documentation/developers-and-admins/saas/xperience-portal.md):

1. Navigate to the **Deployments** application.
2. Select **Deploy to**, located under the environment where the package is currently deployed. A drop-down menu is displayed.
3. Select the environment where you want to deploy the package.
4. Select whether you want to deploy the package immediately or [schedule a production deployment for a later date](#schedule-a-production-deployment-for-a-later-date).

   > **Info:** The SaaS environment checks if the production deployment causes downtime. Most deployments are seamless and incur no downtime, especially if the deployment package is marked as [zero-downtime ready](#zero-downtime-deployments). However, if the system discovers downtime would occur, you can [schedule a production deployment for a later date](#schedule-a-production-deployment-for-a-later-date). It is also recommended to define a custom [App Offline page](https://docs.kentico.com/documentation/developers-and-admins/configuration/saas-configuration.md#define-a-custom-app-offline-file).
5. Allow a minute for the deployment process to be displayed in the **Deployment progress**.

   > **Note:** Repeating the procedure triggers a new deployment.
6. Check the **Deployment history** section to verify the package is deployed to the environment you selected. Note that the deployment may be queued and will begin once previous SaaS processes have finished.

   > **Info:** If you need to debug a failed deployment, see the **Logs** in the **Deployment history** section.

Your application is now deployed and running in the selected environment.

### Schedule a production deployment for a later date

Deployment to a production or staging environment can cause application downtime, impacting the customer experience. [Zero-downtime deployments](#zero-downtime-deployments) minimize or eliminate downtime, but may not be suitable for all deployment scenarios.

When you trigger a deployment with the **Deploy to** action, the SaaS environment reports if the deployment causes downtime. You can decide whether to proceed with the deployment, schedule the deployment, or cancel the deployment.

Select the **Cancel scheduled deployment** button in the **Deployments** application to cancel the scheduled deployment.

> **Note:** Scheduling the production deployment blocks instant production/staging deployment and additional scheduling.
>
> Cancel the existing scheduled deployment in the **Deployments** application to enable these actions.

If the scheduled deployment fails to start, the project's **Tenant administrators** and the user that scheduled the deployment receive a notification email\*\*,\*\* and the production/staging environment is unaffected.

> **Info:** If the scheduled deployment starts successfully, but the deployment pipeline fails, users will not receive a notification email.
>
> See the deployment **Logs** in the **Deployment history** section to debug the failed deployment.

## Specialized deployments

Follow these specialized scenarios when you need to deploy a large amount of initial data or apply emergency fixes in the SaaS environment:

- [Deploy a large amount of data during initial deployments](https://docs.kentico.com/documentation/developers-and-admins/deployment/deploy-to-the-saas-environment/specialized-deployment-scenarios.md#deploy-a-large-amount-of-data-during-initial-deployments)
- [Deploy emergency fixes to the SaaS environment](https://docs.kentico.com/documentation/developers-and-admins/deployment/deploy-to-the-saas-environment/specialized-deployment-scenarios.md#deploy-emergency-fixes-to-the-saas-environment)