CICD Advanced setup - deployment options

umbraco-cloud/SUMMARY.md

@@ -68,6 +68,7 @@
     * [Configuring a CI/CD pipeline](build-and-customize-your-solution/handle-deployments-and-environments/umbraco-cicd/samplecicdpipeline/README.md)
       * [Azure DevOps](build-and-customize-your-solution/handle-deployments-and-environments/umbraco-cicd/samplecicdpipeline/azure-devops.md)
       * [GitHub Actions](build-and-customize-your-solution/handle-deployments-and-environments/umbraco-cicd/samplecicdpipeline/github-actions.md)
+      * [Advanced Setup: Deployment options](build-and-customize-your-solution/handle-deployments-and-environments/umbraco-cicd/samplecicdpipeline/advanced-deployment-options.md)
       * [Advanced Setup: Deploy to multiple targets](build-and-customize-your-solution/handle-deployments-and-environments/umbraco-cicd/samplecicdpipeline/advanced-multiple-targets.md)
       * [Migrate from V1 to V2](build-and-customize-your-solution/handle-deployments-and-environments/umbraco-cicd/samplecicdpipeline/migrate.md)
       * [Deployment Artifact best practice](build-and-customize-your-solution/handle-deployments-and-environments/umbraco-cicd/samplecicdpipeline/artifact-best-practice.md)

umbraco-cloud/build-and-customize-your-solution/handle-deployments-and-environments/umbraco-cicd/samplecicdpipeline/advanced-deployment-options.md

@@ -0,0 +1,131 @@
+# Advanced Setup: Deployment options
+
+Here you will learn how to use the deployment options available with the v2 endpoints for CI/CD.
+
+This provides some control to the CI/CD deployment process within the isolated instance before your code is pushed to the Cloud environment.
+
+## Option: skipVersionCheck
+
+During deployment, the system will do an automatic check for  downgrades of Cloud dependencies. This is to avoid customers from downgrading packages that may have been auto upgraded on Umbraco Cloud, by accident. 
+
+Enabling **skipVersionCheck** will bypass that safeguard and allow deployments that include downgraded packages. 
+
+{% hint style="info" %}
+This option increases risk and is not recommended for normal workflows. Only enable it when you understand the package differences and accept the potential consequences.
+{% endhint %}
+
+## Option: noBuildAndRestore
+
+The Umbraco CI/CD flow runs the deployment in an isolated instance and performs `dotnet restore` and `dotnet build` to catch obvious build issues before deploying to Cloud. Enabling **noBuildAndRestore** skips the restore and build steps in that isolated instance, which can shorten deployment time by a few minutes.
+
+Keep in mind the final Kudu deployment on the Cloud environment will still run **restore**, **build**, and **publish**; those steps cannot be skipped.
+
+## How to enable the options
+
+All the pipeline script generally follow the same structure. But there are some small details to be aware of.
+
+{% tabs %}
+{% tab title="Azure DevOps Bash" %}
+Locate the main entry pipeline file. It will usually be this one: `azure-release-pipeline.yaml`.
+
+```yml
+  # Deploy to Umbraco Cloud
+  # ####
+  # you can edit the variables noBuildAndRestore and skipVersionCheck    
+  # use booleans but as strings
+  - stage: CloudDeploymentStage
+    displayName: Deploy To Cloud
+    dependsOn: cloudPrepareArtifact
+    condition: in(dependencies.cloudPrepareArtifact.result, 'Succeeded')
+    variables:
+      artifactId: $[ stageDependencies.cloudPrepareArtifact.PrepareAndUploadArtifact.outputs['uploadArtifact.artifactId'] ]
+    jobs: 
+      - template: cloud-deployment.yml
+        parameters:
+          artifactId: $(artifactId)
+          noBuildAndRestore: 'false'
+          skipVersionCheck: 'false'
+```
+
+The fields: `noBuildAndRestore` and `skipVersionCheck` can be marked with a `'true'`. 
+
+
+{% endtab %}
+{% tab title="Azure DevOps PowerShell" %}
+Locate the main entry pipeline file. It will usually be this one: `azure-release-pipeline.yaml`.
+
+```yml
+  # Deploy to Umbraco Cloud
+  # ####
+  # you can edit the variables noBuildAndRestore and skipVersionCheck    
+  # use booleans
+  - stage: CloudDeploymentStage
+    displayName: Deploy To Cloud
+    dependsOn: cloudPrepareArtifact
+    condition: in(dependencies.cloudPrepareArtifact.result, 'Succeeded')
+    variables:
+      artifactId: $[ stageDependencies.cloudPrepareArtifact.PrepareAndUploadArtifact.outputs['uploadArtifact.artifactId'] ]
+    jobs: 
+      - template: cloud-deployment.yml
+        parameters:
+          artifactId: $(artifactId)
+          noBuildAndRestore: false
+          skipVersionCheck: false
+
+```
+
+The fields: `noBuildAndRestore` and `skipVersionCheck` can be marked with a `true`. 
+
+
+{% endtab %}
+{% tab title="GitHub Actions Bash" %}
+Locate the main entry pipeline file. It will usually be this one: `main.yml`.
+
+```yml
+  # Deploy to Umbraco Cloud
+  # ####
+  # you can edit the variables noBuildAndRestore and skipVersionCheck    
+  # use booleans but as strings
+  cloud-deployment:
+    name: "Deploy to Cloud"
+    needs: cloud-artifact
+    uses: ./.github/workflows/cloud-deployment.yml
+    with:
+      artifactId: ${{ needs.cloud-artifact.outputs.artifactId }}
+      targetEnvironmentAlias: ${{ vars.TARGET_ENVIRONMENT_ALIAS }}
+      noBuildAndRestore: "false"
+      skipVersionCheck: "false"
+    secrets:
+      projectId: ${{ secrets.PROJECT_ID }}
+      umbracoCloudApiKey: ${{ secrets.UMBRACO_CLOUD_API_KEY }}
+```
+
+The fields: `noBuildAndRestore` and `skipVersionCheck` can be marked with a `"true"`. 
+
+{% endtab %}
+{% tab title="GitHub Actions PowerShell" %}
+Locate the main entry pipeline file. It will usually be this one: `main.yml`.
+
+```yml
+  # Deploy to Umbraco Cloud
+  # ####
+  # you can edit the variables noBuildAndRestore and skipVersionCheck    
+  # use 0 for false and 1 for true
+  cloud-deployment:
+    name: "Deploy to Cloud"
+    needs: cloud-artifact
+    uses: ./.github/workflows/cloud-deployment.yml
+    with:
+      artifactId: ${{ needs.cloud-artifact.outputs.artifactId }}
+      targetEnvironmentAlias: ${{ vars.TARGET_ENVIRONMENT_ALIAS }}
+      noBuildAndRestore: 0
+      skipVersionCheck: 0
+    secrets:
+      projectId: ${{ secrets.PROJECT_ID }}
+      umbracoCloudApiKey: ${{ secrets.UMBRACO_CLOUD_API_KEY }}
+```
+
+The fields: `noBuildAndRestore` and `skipVersionCheck` can be marked with a `1`. 
+
+{% endtab %}
+{% endtabs %}

umbraco-cloud/build-and-customize-your-solution/handle-deployments-and-environments/umbraco-cicd/samplecicdpipeline/azure-devops.md

@@ -243,6 +243,7 @@ If you have frontend assets that needs to be built (using tools like npm/yarn or
 
 Please follow the above guide first.
 
+* [Deployment options](advanced-deployment-options.md) 
 * [Deploy to multiple targets](advanced-multiple-targets.md)
 
 ## Further information

umbraco-cloud/build-and-customize-your-solution/handle-deployments-and-environments/umbraco-cicd/samplecicdpipeline/github-actions.md

@@ -275,6 +275,7 @@ If you have frontend assets that needs to be built (using tools like npm/yarn or
 
 Please follow the above guide first.
 
+* [Deployment options](advanced-deployment-options.md) 
 * [Deploy to multiple targets](advanced-multiple-targets.md)
 
 ## Further information

umbraco-cloud/build-and-customize-your-solution/handle-deployments-and-environments/umbraco-cicd/umbracocloudapi.md

@@ -235,6 +235,9 @@ You can use the deploymentId to query the Get Deployment status endpoint.
 It is not recommended to enable the `skipVersionCheck`. This is to ensure that versions of the different Umbraco packages in the Cloud environment aren't overwritten by older versions. There may be instances where you would like to deploy an older artifact. In those instances it is possible to enable this setting to skip the step.
 
 Enabling the `noBuildAndRestore` only disabled the restore and build inside the isolated instance. Once the system pushes the source code to the environment a build and publish operation will run as usual. One minute or more can be saved during the deployment process by enabling this option.
+
+For more information on using the `skipVersionCheck` and `noBuildAndRestore` setting in the pipeline , see the [Advanced Setup: Deployment options](./samplecicdpipeline/advanced-deployment-options.md) article.
+
 {% endhint %}
 
 ### Get Deployment status