Deploy a project and environment

Timing 10 minutes

This is part one of the getting started walkthrough series. After you complete this step, move on to create a site and page.

When you create a new project in the Deploy app, it automatically creates an environment and runs an initial deployment. In this topic, we'll create a project in the Deploy app. You can also create a project using the Sitecore CLI or the Deploy API.

Note

The number of environments you can create is based on your SitecoreAI subscription.

The steps described here differ, depending on whether you are using Next.js with the Content SDK or the ASP.NET Core SDK.

This walkthrough describes how to:

  1. Open the Deploy app

  2. Deploy a project and environment

Before you begin

Open the Deploy app

You start creating your first project in the Deploy app which you can access directly at https://deploy.sitecorecloud.io/.

To open the Deploy app in the Cloud Portal:

If you belong to multiple organizations, you might need to switch to the desired organization.

Deploy a project with the decoupled deployments architecture (default)

Note

Projects built before January 2026 were deployed using the legacy coupled deployment architecture. We recommend you to convert these projects to use the decoupled deployments architecture.

The Decoupled Deployment feature lets you:

  • Create and manage editing hosts from the Deploy app.

  • Build and deploy the authoring environment and editing host separately, resulting in faster deployments and independent logging.

  • Use the source code from different repositories when adding additional authoring environments and editing hosts to a project.

  • Add custom environment variables during project or environment creation.

To create a project in the Deploy app using the foundation template with decoupled deployment:

  1. In the Deploy app, on the Projects page, click Create project.

    The Create project button in the Deploy app

  2. Name the project Getting Started, make sure Use starter kit is selected, then click Continue.

  3. In the Set up authoring environment window, name the authoring environment Getting Started.

  4. Select the source control provider you want to use for your project. Assuming there is no existing connection, click Add GitHub account or Add Azure DevOps account, and follow the steps to authorize the Deploy app in your account. You can manage the connection for the source control provider later.

  5. After authorizing the Deploy app in your source control provider account, enter a name for the repository the Deploy app will create to store your environment code, such as Getting-Started.

    Note

    Your repository name can only contain alphanumeric characters, underscores, periods, or hyphens, and a maximum of 100 characters. It must also follow the repository naming convention of your source control provider.

  6. Select the Auto deploy on push to repository checkbox and make sure the Production SaaS SLA checkbox is clear.

    Important

    A production environment is optimized for production traffic and is covered by the Sitecore SaaS Service Level Agreement. This setting cannot be changed later.

    At this point, you can add environment variables to your authoring environment, however, it is not needed for this getting started guide, so click Continue.

  7. In the Set up editing host window, select the Auto deploy on push to repository checkbox. Since you are using the starter kit, the Editing host name is preselected for you.

    Setting up an editing host is optional, but it is needed for this getting started guide.

    Note

    If you bring your own code and want to set up an editing host:

    1. To select the editing host source code, in the Editing host name field, enter the name of the rendering host defined in the xmcloud.build.json file of the editing host code repository.

      XM Cloud is now SitecoreAI

      Some code examples, images, and UI labels may still use XM Cloud while engineering assets are being updated.

    2. Choose the source control account and repository that contains the editing host code.

      For more information, see manage an editing host.

    At this point, you can add environment variables to your editing host, however, it is not needed for this getting started guide, so click Continue.

  8. Review the configuration and click Start deployment.

  9. The deployment runs for a few minutes, and you are redirected to the deployment log screen to see the progress (this might take a few seconds). After it completes, you can go to SitecoreAI and create a new site.

Tip

If your deployment fails, you can access the deployment log to investigate what happened and attempt to rerun the deployment.

The Deploy Settings UI

The deployment process:

  • Creates a new repository in the connected source control account and copies the source code from the foundation template to the new repository.

  • Provisions the infrastructure and SaaS tenants to host the Content Management (CM) instance in the environment you defined.

  • Pulls the source code from the repository to a hosted SitecoreAI build server and builds the solution.

  • Deploys the build artifacts on the provisioned CM instance.

Now that you've provisioned the project and environment, the environment appears as an app in the Sitecore Cloud Portal.

The next thing you'll do is create a site and page.

Deploy a project with the legacy coupled deployment architecture

Withe the legacy arhictecture, when you create a new project in the Deploy app, it automatically creates an environment and runs an initial deployment there. Because the Decoupled Deployments architecture is the default deployment, follow these instructions to enable the legacy coupled deployment architecure:

  1. Go to Settings.

  2. Disabled the Use the Decoupled Deployments toggle.

The Deploy Settings UI

Content SDK (Next.js)

If you are creating a Content SDK app, in this walkthrough, you create a project using the Content SDK starter kit in a ready-made flow in the Deploy app.

To deploy a Content SDK project in the Deploy app:

  1. In the Deploy app, on the Projects page, click Create project.

    The Create project button in the Deploy app

  2. Name the project, for example, Getting Started, then click Continue.

  3. To choose the source control provider you want to use for your project click Connect, then Continue. The Deploy app will create a new repository there to store your environment code.

  4. In the Set up repository step, make sure Use XM Cloud template is selected.

    XM Cloud is now SitecoreAI

    Some code examples, images, and UI labels may still use XM Cloud while engineering assets are being updated.

  5. Assuming there is no existing connection, click Connect to a new account, and follow the steps to authorize the Deploy app in your account. You can later manage the connection for the source control provider.

  6. Enter a name for the repository, such as Getting-Started, then click Continue.

    Note

    Your repository name can only contain alphanumeric characters, underscores, periods, or hyphens, and a maximum of 100 characters. It must also follow the repository naming convention of your source control provider.

  7. Name the environment, for example, Getting Started.

  8. In the Production SaaS SLA field, select No.

    Important

    A production environment is optimized for production traffic and is covered by the Sitecore SaaS Service Level Agreement. This setting cannot be changed later.

  9. In the Auto deploy on push to repository field, select Yes.

  10. Review the configuration and click Start deployment.

  11. The deployment runs for a few minutes, and you are redirected to the deployment log screen to see the progress (this might take a few seconds). After it completes, you can go to SitecoreAI and create a new site. The deployment creates a new repository in the connected source control account and copies the source code from the foundation template to the new repository.

Tip

If your deployment fails, you can access the deployment log to investigate what happened and attempt to rerun the deployment.

The deployment process:

  • Creates a new repository in the connected source control account.

  • Provisions the infrastructure and SaaS tenants to host the Content Management (CM) instance in the environment you defined.

  • Pulls the source code from the repository to a hosted SitecoreAI build server and builds the solution.

  • Deploys the build artifacts on the provisioned CM instance.

Now that you've provisioned the project and environment, the environment appears as an app in the Sitecore Cloud Portal.

The next thing you'll do is create a site and page.

A project is a logical grouping of environments. Each project can include several environments, such as a development, testing, and production environment. In SitecoreAI, you can create a project using the Deploy app, the CLI, or REST APIs.

When you create a project using the Deploy app, one environment is automatically created, and you can choose whether it’s a production environment (that gets faster support than the non-production environments). The number of projects you can create depends on your subscription.

An environment is an entity that holds a set of configurations, code, and implementations. Each environment includes the following:

  • A single content management (CM) instance

  • Experience edge tenant

  • Databases

  • Indexes

  • Automation clients

  • Environment variables

  • Rendering hosts

  • An app tenant that connects the CM instance with functionality such as Pages and Components

Each environment is isolated and unique. This allows you to have unique customizations, deployments, and configurations on your environment, based on implementation needs.

The starter kit is a code base that’s intended to be the basis of most implementations for ASP.NET Core applications. To use it, follow the use your own code flow when getting started with SitecoreAI. It is open source, and available on GitHub. Using the starter kit ensures you get the most stable and up-to-date version of the assets, references, assemblies, and artifacts we recommend using when you start building a solution with SitecoreAI.

Do you have some feedback for us?

If you have suggestions for improving this article,