Deploy code changes

Sitefinity Cloud is configured in a CI/CD setup, in accordance with Sitefinity website development best practices and Microsoft Azure services that are being used.  

Code deployment is the process that validates and pushes changes to the Sitefinity Cloud project. It is done through a CI/CD pipeline, which consists of tasks and conditions, ensuring the successful pushing of new code to the corresponding environment.

By default, the deployment workflow is in line with the software development practice of Continuous Delivery (CD) for deploying new changes across environments. During this process, the deployment package is prepared from the main/master branch of the repository and is then subsequently deployed to each environment, following an approval/verification/testing step until reaching Production. By following these best practices, committing your changes directly to the main/master branch is restricted. Instead, all code development must be done in a dedicated feature branch, which you create from main/master branch, and then you merge your changes into main/master via pull request from the feature branch.

This flow can be customized according to the customer needs. For example, there can be a different branch or set of branches configured for each environment. The process of merging pull requests between branches will trigger a build and deploy to the environment of the target branch. In addition, you can configure deployments to any environment to be triggered manually.

The same is valid for the ASP.NET Core Renderer application repository that is available with the ASP.NET Core Renderer add-on.

Create a feature branch

Creating a new feature branch for development follows the standard Git development workflow. If you have cloned your Sitefinity Cloud project solution in Visual Studio, perform the following:

1. Clone the main/master branch to begin local development. Follow the procedure Set up the project for local development » Setting up the project code locally.
2. From your Visual Studio Team Explorer, locate the main/master branch, right click on it and select New Local Branch From...
3. Name your new branch and create it.
   
   

As a result, your feature branch for local development is created and you can proceed with your project development.

Include resource files in the Visual Studio project

If you have added new resource files, such as configurations, resource files, JavaScript, or CSS, you must include them in the Visual Studio project:

1. Open your project in Visual Studio.
2. In the Solution Explorer, in the context menu of the resource, click Include In Project.
3. In the Properties pane of the resource, set the Build Action to Content.

If you do not do this, the file will not be added to the deployment package that will be deployed later. For more information, see Troubleshooting » Deployment package.

Commit your changes and sync them to Sitefinity Cloud

When you are done with your changes, you must commit them via the Visual Studio Team Explorer » Changes screen. This action commits your changes only to the local branch.

Once you are ready with your changes and want to deploy them to Sitefinity Cloud, use the Visual Studio Team Explorer » Sync screen to push your changes to Sitefinity Cloud. This operation will synchronize your new feature branch and the committed changes.

Develop with ASP.NET Core Renderer

The ASP.NET Core Renderer add-on in Sitefinity Cloud enables you to take advantage of a three-tier application architecture and build your frontend presentation layer using ASP.NET Core. 
For more information, see the ASP.NET Core Renderer documentation » Three-tier architecture.

When you set up the ASP.NET Core Renderer application locally, you can configure it to work with your local setup of the Sitefinity CMS application - in case you need to do simultaneous development work on both applications. For general information about setting up the ASP.NET Core Renderer, see the ASP.NET Core Renderer documentation » Setup.

You can also configure your local ASP.NET Core Renderer application to work directly with the Sitefinity CMS application that is deployed on one of the non-Production cloud environments. This option provides for a quick setup and allows developers to use Linux or MacOS, because they do not need to setup the Sitefinity application and Database locally.
The following diagram visualizes how you connect a local ASP.NET Core Renderer application with Sitefinity CMS and ASP.NET Core Renderer deployed in the cloud:

In Sitefinity Cloud, you have both the Sitefinity CMS and the ASP.NET Core Renderer applications deployed and running on each environment. The Cloudflare CDN acts as an entry point for all requests.

When you connect your local ASP.NET Core Renderer application to a Sitefinity CMS application instance hosted in the cloud, you must instruct the cloud hosted ASP.NET Core Renderer instance to stop acting as a renderer, and start acting as a proxy instead.
To achieve this, you have to configure the LocalValidationKey property of the ASP.NET Core Renderer application. Your local ASP.NET Core Renderer will send the LocalValidationKey with each request. When the HTTP request reaches the cloud hosted ASP.NET Core Renderer, it will compare the incoming LocalValidationKey with its own RemoteValidationKey. If they match, then the setup will be successful, and you will be able to develop locally against the cloud hosted version of the Sitefinity CMS application.

To configure the LocalValidationKey property of the ASP.NET Core Renderer application, perform the following:

1. Navigate to your dedicated Key Vault instance in the Azure portal.
   For more information, see Azure Key Vault.
2. On the Key Vault left-hand sidebar, select Objects and then select Secrets.
3. Select LocalValidationKey and from the listed versions, select the current version of the value.
4. In the dialog that opens, copy the value specified in Secret value.
5. On your local Renderer, edit the appsettings.json file and under “Sitefinity” section, add the validation key and edit the URL in the following way:
6. Save and close the file.

Once your feature branch with the desired changes has been synchronized to Sitefinity Cloud, you are able to proceed by merging these changes to the project main/master branch and deploy them to the Staging environment.

Create a pull request to push your code to the main/master branch

Proceed by following these steps:

1. Log in to your Sitefinity Cloud project Management Portal.
2. Navigate to Repos » Pull requests and click New pull request.
3. From the source branch selection dropdown, select the feature branch you want to merge changes from. From the target branch selection dropdown, select main/master.
4. Fill in the pull request details and proceed by clicking Create.
   
   

Approve and merge pull requests

Each pull request must be approved before merging the changes to the main/master branch. By default, all users who are in the Contributors role can approve pull requests. To view pull requests that are pending approval and approve them, follow these steps:

1. In your Sitefinity Cloud Management Portal, navigate to Repos » Pull requests and click the Active tab.
2. Click the name of desired pull request from the list.
3. On the next screen, you can review the pull request and approve it by clicking Approve.

As a result, all policy requirements are marked as met and an automated CI build is triggered to test the changes against the main/master branch. To complete merging the changes, click Complete (located next to the Approve button).

NOTE: Once the merge is successfully completed, the feature branch is automatically deleted as it is no longer needed.

Approving a merge triggers an automated CI build and upon successful completion, the changes are merged in the main/master branch and a deployment is triggered to apply the changes on the corresponding non-Production environment(s). You can browse the non-Production environment(s) where the changes have been deployed to verify your newly deployed functionality is working as expected.

Promote your code to the Production environment

1. In your Sitefinity Cloud Management Portal, navigate to Pipelines » All.
2. Select CI.CD.
3. Locate the Run that is pending approval to Production and open it.
4. Click Review next to the message 1 approval needs your review before this run can continue to Production

5. In the dialog box that opens, click Approve or Reject.

The non-Production environment(s) can also be configured to require approval from users in a Promote to {Environment Name} group.

The CI stage of the pipeline uses the built-in Azure DevOps Cache task to cache NuGet packages across builds. 
For more information, see Azure DevOps documentation » Cache task.

This reduces the time it takes to execute the CI stage, because NuGet packages are downloaded from the cache, instead of restored from scratch on each run. The cache key is based on the contents of all packages.config files. This way, the cache is not being used in case packages change.

The deployment process intelligently checks for the exact file changes between the previously deployed commit and the current one. If you have made changes only to files that do not require application restart, such as JavaScript, CSS, TXT files, the deployment process detects this and performs a partial deployment, which is much faster. 

The preview deployment functionality checks that the newly deployed version of the application on Production can start up and pages can be precompiled using a DB copy from Production before switching to the actual Production DB. This is important in case of DB schema changes and Sitefinity upgrades that come with the new deployment package, because if the application fails to start or corrupts the DB copy, the actual Production DB will not be affected.

To deploy the ASP.NET Core Renderer to Sitefinity Cloud, use the DotNetCoreRenderer.CI.CD pipeline. The rest of the deployment process does not differ from a standard Sitefinity CMS app deployment.

For more information, see ASP.NET Core Renderer.

To facilitate the needs of customizing the CI/CD process, Sitefinity Cloud offers a mechanism for extending the existing CI/CD pipeline and include custom tasks for the following events:

• Pre-build tasks in CI stage
• Post-build tasks in CI stage
• Post-deployment tasks in CD stage

Customize CI stage in CI/CD pipeline of Sitefinity

1. Open the CICD.yaml file located in the repository of the Sitefinity project.
2. Locate the parameters element for the extended CICDTemplate.yaml.
3. Add a new parameter of type stepList called preBuildSteps or postBuildSteps, and add tasks using the standard YAML task/step syntax.

The example below demonstrates custom pre-build steps installing and building frontend assets with npm, and post-build steps for running unit tests:

Customize CD stage in CI/CD pipeline of Sitefinity

1. Open the CICD.yaml file located in the repository of the Sitefinity project.
2. Locate the parameters element for the extended CICDTemplate.yaml.
3. Define environments collection and list the environments where CD stage needs to be customized.
4. Add a new parameter of type stepList called postReleaseSteps as part of the environment object, and add tasks using the standard YAML task/step syntax.

The custom steps are defined per environment and only an allowed list of task types can be used. Currently the allowed task types are:

• DownloadPipelineArtifact@2
• VisualStudioTestPlatformInstaller@1
• VSTest@2

The example below demonstrates a custom post-release task to run web tests, based on an artifact called tests:

Customize CI stage in CI/CD pipeline of ASP.NET Core Renderer

1. Open the CICD.yaml file located in the repository of the ASP.NET Core Renderer project.
2. Locate the parameters element for the extended CICDDotNetCoreRendererTemplate.yaml.
3. Add a new parameter of type stepList called preBuildSteps or postBuildSteps, and add tasks using the standard YAML task/step syntax.

The example below demonstrates custom pre-build steps for adding custom NuGet sources and post-build steps for running unit tests: