dotnet sitecore cloud deployment create --environment-id <id> --upload --working-dir <path><\/code><\/pre>\n\n\n\nAlthough you now have more options and control, it still is not desirable to run this manually from your development workstation. But we can use this CLI command in our pipelines and build a decent deployment process that fits well into the bigger picture of our deployment strategy (we have multiple pipelines for multiple applications within our landscape, from front-end to individual microservices).<\/p>\n\n\n\n
Don’t reuse the deployment command<\/h2>\n\n\n\n
As you probably already know when reading this blog post, there’s a hierarchy to XM Cloud environments. A “Project” defines as the top-level entity, containing multiple “Environments”, usually at least two non-production environments (like test and acceptance or UAT) and one production environment. When you start a deployment, you always deploy to a specific environment: as you can see in the above example, the cloud deployment<\/code> command takes a (required) parameter named --environment-id<\/code>.<\/p>\n\n\n\n\nWhile this implies that you can use that deployment command to deploy to each environment of your XM Cloud project individually, that isn’t the way to go!<\/p>\n<\/blockquote>\n\n\n\n
Script-wise it is very easy to use the above deployment command to deploy to each of your environments, only passing the corresponding environment ID into the pipeline and you’re good. But for a decent deployment strategy, I would go the extra mile of utilizing the build promotion mechanism that is built into XM Cloud.<\/p>\n\n\n\n
Promoting deployments<\/h2>\n\n\n\nWhy?<\/h3>\n\n\n\n
There are two important reasons to promote an existing build to other environments instead of creating a new deployment per environment:<\/p>\n\n\n\n
\n- Saving time: promoting is even quicker than deploying as it skips the build step<\/li>\n\n\n\n
- Guaranteed the same build & version, which is important for a representative (acceptance) test preceding a production deployment, ensuring a proper DTAP process<\/li>\n<\/ul>\n\n\n\n
When you check out the deployment logs in the Sitecore Cloud portal you can see promotion skips the build step (as it is re-using the same build), saving about 25% of the initial deployment time:<\/p>\n\n\n\n![\"\"](\"https:\/\/www.robhabraken.nl\/wp-content\/uploads\/2023\/10\/deployment-promotion-1024x753.png\")
<\/figcaption><\/figure>\n\n\n\nThe mechanism<\/h3>\n\n\n\n
When you are using the CLI you need to take the following steps to be able promote your builds:<\/p>\n\n\n\n
\n- Create a deployment without starting it (using the
--no-start<\/code> option)<\/li>\n\n\n\n- Retrieve and store the deployment ID<\/li>\n\n\n\n
- Execute a
cloud deployment start<\/code> command referencing the ID<\/li>\n\n\n\n- When you want to promote your build to another environment, use the
environment promote<\/code> command with the deployment ID as input for the --source-id<\/code> option<\/li>\n<\/ul>\n\n\n\nIf you would start your deployment right away, as shown in the above example, you won’t retrieve a deployment ID and thus are not able to promote that build using the CLI<\/em> (of course, you can always do that via the Sitecore Cloud portal but that’s not what we’re after).<\/p>\n\n\n\nThe promote command<\/h3>\n\n\n\n
While promoting deployments is a deployment in way, this CLI command actually isn’t a subcommand of cloud deployment<\/code> but of the cloud environment<\/code> command. This makes it less apparent when you are creating a deployment script using the deployment command as a guide in the documentation. The environment command is used to create, update and list environments, but also promote a build from one environment to another: https:\/\/doc.sitecore.com\/xmc\/en\/developers\/xm-cloud\/the-cloud-environment-command.html#the-promote-subcommand<\/a>.<\/p>\n\n\n\nStoring and passing the deployment ID<\/h3>\n\n\n\n
So, the theory is quite simple. But getting the YAML pipeline to actually return and store the deployment ID using powershell steps to execute Sitecore CLI commands is a bit of a challenge. Thanks to my colleague Rinus Leenders for figuring out the works, we can now share our fully scripted deployment pipeline for Azure DevOps in YAML. We are utilizing the ##vso[task.setvariable]<\/code> command, which is a special syntax recognized by Azure DevOps environments, informing the system to set a variable accordingly.<\/p>\n\n\n\nThis leads to the following PowerShell script to store the deployment ID in your pipeline when creating a new deployment:<\/p>\n\n\n\n
$deployment = dotnet sitecore cloud deployment create --environment-id $env:XMC_ENVIRONMENT_ID --no-watch --no-start --upload --working-dir $(Build.SourcesDirectory) --json | ConvertFrom-Json\nWrite-Host \"$deployment\"\n$deploymentId = $deployment.id\nWrite-Host \"##vso[task.setvariable variable=deploymentId]$deploymentId\"\nWrite-Host \"##vso[task.setvariable variable=deploymentId;isOutput=true]$deploymentId\"<\/code><\/pre>\n\n\n\nAfter which we can use that variable to start the deployment right away:<\/p>\n\n\n\n
dotnet sitecore cloud deployment start --deployment-id $(deploymentId) --json | ConvertFrom-Json<\/code><\/pre>\n\n\n\nAnd subsequently promoting that build to another environment as part of the deployment pipeline to our acceptance and production environments (encompassing more parts and pipelines, as we simultaniously and \/ or individually would want to deploy our front-end and microservices as well, but that’s outside the scope of this blog post):<\/p>\n\n\n\n
dotnet sitecore cloud environment promote --environment-id $env:XMC_ENVIRONMENT_ID --source-id $(deploymentId)<\/code><\/pre>\n\n\n\n
![\"\"](\"https:\/\/www.robhabraken.nl\/wp-content\/uploads\/2023\/11\/github-xmcloud-deploy-1024x594.png\")