Documentation

This is the early access documentation preview for Custom Views. This documentation might not be in sync with our official 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 is the source of truth and it is the only branch that you can deploy to the staging and production environments.

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

The branch deployments work seamlessly with the Netlify Deploy Previews feature. When you create a pull request, the commercetools Frontend CI builds your backend, while Netlify deploys your frontend website. 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.

Your Netlify administrator must configure Deploy Previews on Netlify.

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.

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.

From the Studio, you can only deploy builds for the master branch. Even if builds for other branches appear in the Builds available dialog, you cannot deploy them.

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.

If a version mismatch error message displays next to the Short commit hash field, you can resolve it by creating a new deployment from the Studio.

The error occurs when a manual deployment is triggered from the Netlify dashboard or the auto-publishing lock is deactivated on Netlify.

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.