Back to post list

XM Cloud series: What about Azure DevOps? (Or others)

By Derk Hudepol on 11/11/2022

Introduction

When starting with XM Cloud you will notice that all the documentation points towards using GitHub for storing your code so that you can connect GitHub to XM Cloud and leverage the tight integration so that XM Cloud automatically picks up on commits into the selected branch. However it can happen that you are not able to use GitHub for your customers and are required to leverage another tool.

In this post I will go into how to setup XM Cloud with Azure DevOps but the principles can actually be used for other code repository tooling as well by leveraging the XM Cloud CLI.

What is Azure DevOps?

Azure DevOps Server is a Microsoft product that provides version control, reporting, requirements management, project management, automated builds, testing and release management capabilities.

That being said a lot of companies leverage Azure DevOps for version control based upon git whilst also leveraging the automated build and release functionalities. This is also the case for company I work at and most of our customers.

Creating the XM Cloud environment without the deploy app

Because the deploy app from Sitecore only supports GitHub as a code platform we will need to leverage the Sitecore Cloud CLI.

Before creating the environment we will need source code to deploy to the XM Cloud environment we are going to create. For this purpose we will leverage the SxaStarter project that sitecore makes available on the sitecorelabs github( i am going a little deeper into using this project in my previous blogpost). Simply clone this repository by leveraging the command below, if you have already got the codebase locally you can skip this step.

1git clone https://github.com/sitecorelabs/xmcloud-foundation-head-staging.git sxa-starter

After cloning the repository open up a powershell window and make sure the context of the window is the folder which you have just cloned the sxastarter template into. If you have only now cloned the repository you will need to run the dotnet tool restore command:

1dotnet tool restore

This will install the Sitecore CLI with the required plugins.

Now that we have the CLI installed we can start setting things up. We can start by logging into sitecore, by running the command below you will open a bowser window where you will need to login to Sitecore cloud services.

1dotnet sitecore cloud login

After you have succesfully logged in we can start setting up the project in which we want to create the environment. This can be achieved by running the command below:

1dotnet sitecore cloud project create --name "<choose-a-name-here>"

The output of the command should be similar to below:

1XM Cloud Project creation was successful!
2'Test' Project was created within 'weu (West Europe)' Region for the '********' Organization.
3The 'Test' Project was assigned a Project Id of '***********'
4To add an environment to this Project using the following command:
5dotnet sitecore cloud environment create --project-id <project-id> --name <environment-name>

it is important the capture the project-id here. Please keep this somewhere so we can use it further in the process.

Now we will need to create a environment, this can be done by the command below:

1dotnet sitecore cloud environment create --project-id <project-id-here> --name <environment-name-here>

If the command is succesfull you should see something similar to the output below:

1XM Cloud Environment creation was successful!
2'Test' Environment was created within 'Test' Project for the '**********' Organization.
3Organization Id   : **************
4Organization Name : ******************
5Project Id        : 2EeZudkrqV84KS91loMcMI
6Project Name      : Test
7Environment Id    : 5R9CHQfLDONeyaIFNO3anO
8Environment Name  : Test
9Created by        : derk.hudepol@*****************
10Created at        : 06/11/2022 19:03:26
11
12To add a deployment to this Environment using the following command:
13dotnet sitecore cloud deployment create --environment-id 5R9CHQfLDONeyaIFNO3anO

Important in this output is the environment id as we will need it later. Keep this value save for later. We now have a environment created but we cannot use it yet as there is no deployment created so far.

To deploy code to our instance and create the instance itself we will need to create a deployment and upload our code to xm cloud. This can be achieved by using the following command:

1 dotnet sitecore cloud deployment create --environment-id <environment-id-here> --upload

By running the command our code is uploaded to the XM Cloud environment and XM Cloud will start a build & provisioning agent to setup our environment with the sxastarter code. This process will take between 7-15 minutes the first time so you can sit back and wait untill its done and shows you the output similar to below:

1Deployment '7m82AWUVVSH8rx7eWJeH4K' has been created for the environment '5R9CHQfLDONeyaIFNO3anO'.
2Deployment has been started
3To see realtime progress go to: https://deploy.sitecorecloud.io/deployment/7m82AWUVVSH8rx7eWJeH4K/details
4
5| Provisioning | Complete | 03m:14s |
6| Build        | Complete | 03m:52s |
7| Deployment   | Complete | 03m:24s |
8| PostAction   | N/A      | 00m:01s |
9| Calculated   | Complete | 07m:22s |
10
11Deploy completed
12Your deployment is complete and the Sitecore CM instance is available here:
13https://xmc-**********-bdrtest-tfe3.sitecorecloud.io/

You can now copy the link on the last line and add "/sitecore" to the end and browse to the new environment and you should be able to work with it straight away:

We are now done with setting up our environment so we can continue with preparing for integrating Azure DevOps with XM Cloud

Preperations for integration Azure DevOps with XM Cloud

One of the first things we will need to do is create a Automation Client in XM Cloud. We will need a automation client so that we can deploy to XM Cloud without needing a account.

To create a Automation client go to https://deploy.sitecorecloud.io/auth-clients/organization. You can choose what kind of automation client you want :

  • Organization: this is an automation client that is valid for the whole organization and not just specific environments

  • Environment: this is an automation client that is valid for specific environments

For this post i will assume you are going to create a organization key. Click generate in the organization Automation clients overview and fill in a name:

Generate the key and take a look at the resulting dialog. You will need two values : "Client ID" and "Client Secret", copy these before continuing:

Now that you have the key there is only one thing left : you will need to make sure the code of the sxastarter template we have cloned in the beginning is in a Azure DevOps project. These are steps I wont detail in this post as they are standard steps when working with Azure DevOps and pushing code to a respository so for the next step I will assume the code is in an Azure DevOps project.

Setting up a Azure DevOps pipelines to integrate DevOps with XM Cloud

Now we will setup a Azure DevOps release pipeline. To do this we will open up our Azure DevOps project and go to the "pipelines" section where we can create a new pipeline in our code repository:

Click "new pipeline" and then proceed with selecting the right code repo. When DevOps is offering you starter templates just choose the "starter pipeline":

Before inputting the right YAML code lets setup the variables for the "Client ID","Client Secret" and "Environment ID". Start by clicking variable and then adding the 2 variables with their values, make sure to set them as "secret":

Now we can add the YAML script that defines the release to XM Cloud. You will need the following script:

1# Starter pipeline
2# Start with a minimal pipeline that you can customize to build and deploy your code.
3# Add steps that build, run tests, deploy, and more:
4# https://aka.ms/yaml
5
6trigger:
7- none
8
9pool:
10  vmImage: windows-latest
11
12steps:
13- task: PowerShell@2
14  env:
15      CLIENT_ID: $(Client ID)
16      CLIENT_SECRET: $(Client Secret)
17      ENVIRONMENT_ID: $(Environment ID)
18  inputs:
19    targetType: 'inline'
20    script: |
21      # Write your PowerShell commands here.
22      
23      cd "$(Build.SourcesDirectory)"
24      
25      dotnet tool restore
26      
27      dotnet sitecore cloud login --client-id "$env:CLIENT_ID" --client-secret "$env:CLIENT_SECRET" --client-credentials
28
29      dotnet sitecore cloud deployment create --environment-id $env:ENVIRONMENT_ID --upload
30

In this script we leverage the powershell task and start out by setting the environment variables with our secret variables, otherwise we wouldn' t be able to access them:

1  env:
2      CLIENT_ID: $(Client ID)
3      CLIENT_SECRET: $(Client Secret)
4      ENVIRONMENT_ID: $(Environment ID)

Then in the inline powershell script we take a number of steps:

1  inputs:
2    targetType: 'inline'
3    script: |
4      # Write your PowerShell commands here.
5      
6      cd "$(Build.SourcesDirectory)"
7      
8      dotnet tool restore
9      
10      dotnet sitecore cloud login --client-id "$env:CLIENT_ID" --client-secret "$env:CLIENT_SECRET" --client-credentials
11
12      dotnet sitecore cloud deployment create --environment-id $env:ENVIRONMENT_ID --upload
13

  1. We set the context to the source directory. This is to set the right context to start our release in

  2. we run the dotnet restore command to install the Sitecore Cloud CLI

  3. Now we login to XM Cloud leveraging the Client ID & Client Secret.

  4. Last (but not least) we create a deployment with the --upload parameters to upload the source in DevOps to XM Cloud and have XM Cloud build our code and environment

Now you can click "save and run". if everything went well you should see something similar to below show up:

If everything went well you should now have a functioning release pipeline for XM CLoud in Azure DevOps! Offcourse you will still need to enrich it by adding triggers, unit testing functionalities and maybe even a Automated UI test but the start is there and you are connected to XM Cloud

Summary

Although Sitecore only offers a direct integration with GitHub out of the box, they still kept in mind other Version control software by having the CLI and Automation clients. By following some simple steps we are able to setup integration between Azure DevOps and XM Cloud.

This is a good first step on our DevOps journey for XM Cloud and one of the next would be doing the same kind of integration but will Vercel. I will create a post around that in the near future.