Documentation

Deployment overview

Learn how to build and deploy your website.

If you are using a custom Git repository, you must set up a CI yourself.

commercetools Frontend development follows a trunk-based model, where the master branch serves as the source of truth and it is recommended to be the branch that you deploy to the staging and production environments.
If you need to deploy a different branch to the staging and production environments, we recommend using a custom CI.

Branch deployments

When you push a commit to your repository, the commercetools Frontend CI automatically detects the change and creates a new build for this branch. The build of the master branch is deployed to the staging environment. The build of any other branch is deployed automatically when a request comes for the build version. Once deployed, a build remains active for one hour, after which it is removed and can be reactivated with a new request if space is available for a new branch deployment.

The Studio builds and maintains multiple versions of the backend build so that the extension runner can activate the extensions for any branch deployments based on the incoming frontend request.

Your project can have up to 20 active branch deployments. If you exceed this limit, new branch deployments will be rejected, and requests to the branch deployment from your website will result in a 503 response code.

How backend and frontend builds are connected

When you create a pull request, the commercetools Frontend CI deploys your backend, while Netlify deploys your frontend site. Using this approach, you can preview and test both your backend extensions and frontend code together.

To ensure the frontend deployment on Netlify is connected to the backend extensions from the same build version, the API hub uses the Git commit hash of the build version because this is the same for the backend and frontend build.

By default, you can access deploy previews for pull requests on the master branch directly from the Frontend previews area in the Studio. To see deploy previews for other branches, you must configure your Netlify settings or talk to your Customer Success Manager.

You might get a slow response for the first request to the extensions, and in rare cases, the request could timeout. If this happens, resend the request after one or two minutes.

Test the build

Successful master builds are automatically deployed to your staging environment, where you can test your changes before promoting the build to the production environment.

The master build for the frontend is deployed automatically to your staging site on Netlify. You can use the staging site to test changes before promoting them to the production environment.

Deploy a build

Studio deployment process

The Studio deploys both the frontend and backend build for your project. To handle deployments robustly, the Studio follows this process:

  1. It builds and deploys the backend. If the build fails, the process stops and deployment fails.
  2. It verifies if the backend build is deployed successfully. If not, the process stops and deployment fails.
  3. It initiates the frontend build and deployment on Netlify. If this fails, the previous frontend production deployment will continue to work correctly because the previous backend extensions are available. For more information, see Branch deployments.

You can deploy a build using the command-line or by using the Studio.

Deploy using the command-line

To deploy using the command-line, follow these steps:

  1. From the Studio home page or from the left menu, go to Developer > Deployment.
  2. Click Deploy from command line expandable section.
  3. To copy the command, click the content of the section.
  4. Open a command-line tool on your computer and paste the command.
  5. Replace ####.##.##.##.## with the build version you want to deploy.
  6. To run the command, press Enter.

Do not deploy directly from Netlify. It causes issues with your deployment due to inconsistencies between builds.

Deploy using the Studio

To deploy a build version, follow these steps:

  1. From the Studio home page or from the left menu, go to Developer > Deployment.
  2. In the Deployment expandable section, click Deploy new version: the Builds available dialog opens.
  3. Click the build you want to deploy.

Do not deploy directly from Netlify. It causes issues with your deployment due to inconsistencies between builds.

We recommend deploying only builds for the master branch.

View deployment details

To view the details of a deployment, follow these steps:

  1. From the Studio home page or from the left menu, go to Developer > Deployment.
  2. In the Deployment expandable section, you'll see the current deployment's API URL, short commit hash, and date and time of the build release.

Do not deploy directly from Netlify. It causes issues with your deployment due to inconsistencies between builds.

A version mismatch error message appears next to the Short commit hash field if you trigger a deployment from the Netlify dashboard or the auto-publishing lock is deactivated on Netlify. You can resolve the problem by creating a new deployment from the Studio.

Roll back deployment

To roll back a deployment, follow these steps:

  1. From the Studio home page or from the left menu, go to Developer > Deployment.
  2. In the Deployment expandable section, click Deploy new version: the Builds available dialog opens.
  3. Click the build you want to roll back to.