Commence the XM Cloud deployment seamlessly from GitHub by leveraging Git Actions
We were working on one migration project for our esteemed client where we need to reimplement/migrate their Sitecore XP site to headless XM Cloud.
I hope, we all know, the core concepts and how to setup project, environments and deployments. If you are new to XM Cloud world, you can follow my article on these concepts "Getting familiar with Sitecore XM Cloud Interfaces & Terminologies" and how to manage projects and environments here "Quickest way to start with XM Cloud Instance with Portal Wizard"
Problem Statement
As part of initial setup, you need to create a project and integrate your GitHub account to XM Cloud, so that XM Cloud can trigger the deployment as an when it detect any push/commit to the targeted repository/branch.
One of the biggest pre-requisites for this GitHub integration is, it need "All Repositories" access highlighted in green below.
This could be a biggest road blocker for you from your client as any enterprise level client will not allow you to have access to all their repositories that they may have other code bases for all other projects client may have.
You might think that, in this screenshot, we do have option for selecting "Only select repositories" to select the repository that is dedicated for the current project, something like below.
But when you proceed with this option, we get below exception.
"Integration failed. something went wrong. Uninstall your app from GitHub account manually. You can close this tag and try again" error.
Means, you can't proceed further as you are blocked with both option. You can't have access to all repositories and if moving ahead with single repository selection, the app will not be able to installed perfectly in Git.
So what to do?
Solution Approach
In this situation, Sitecore CLI and Git actions come to rescue us. For the initial setup, we can use Sitecore CLI to create a project, create an environment under that project and deploy the code from local development machine. Sitecore provide a "Step by Step" document to do so and you can follow below URL https://doc.sitecore.com/xmc/en/developers/xm-cloud/walkthrough--creating-an-xm-cloud-project-using-the-sitecore-cli.html
But you don't want to trigger deployment from your local again and again as an when needed. Now, to automate this, we have Git Actions.
To enable Git action, what we can do it is simply create required folders and CLI one yml file that contains CLI commands. To do so, you can follow the article here https://docs.github.com/en/actions/quickstart
Once you are done with required folder structure, you can create a .yml file and paste the below commands into that file.
name: XM Cloud
on:
push:
branches: [ develop ]
paths-ignore:
- 'README.md'
- '.github/workflows/deploy-renderingHost.yml' #IGNORE CHANGES TO GITHUB ACTIONS
- '.github/workflows/deploy-renderingHost-pr.yml' #IGNORE CHANGES TO GITHUB ACTIONS
- 'src/Project/[RH ROOT]/rendering/**' #IGNORE CHANGES TO Next.js head
jobs:
deploy-production:
name: Deploy the XM Cloud Site to the Production Environment
runs-on: [ windows-latest ]
environment: production
steps:
- uses: actions/checkout@v3
- uses: actions/setup-dotnet@v2
with:
dotnet-version: '6.0.x'
- run: dotnet tool restore
- run: dotnet sitecore --help
- name: Authenticate CLI with XM Cloud
run: dotnet sitecore cloud login --client-credentials --client-id ${{ secrets.XM_CLOUD_CLIENT_ID }} --client-secret ${{ secrets.XM_CLOUD_CLIENT_SECRET }}
- name: Deploy the CM assets to XM Cloud
run: dotnet sitecore cloud deployment create --environment-id ${{ secrets.PRODUCTION_XM_CLOUD_ENVIRONMENT_ID }} --upload
- name: Authenticate default environment with CLI
run: dotnet sitecore login --ref xmcloud --client-credentials true --client-id ${{ secrets.XM_CLOUD_CLIENT_ID }} --client-secret ${{ secrets.XM_CLOUD_CLIENT_SECRET }} --cm ${{ secrets.PRODUCTION_XM_CLOUD_CM_URL }} --allow-write true
- name: Publish content changes
run: dotnet sitecore publish --pt Edge
If you pay little attention to above code, you may find that, we have couple of variables like
Recommended by LinkedIn
You may define these variables in GitHub itself in Settings => Secrets and variables => Actions => New repository secret
But if you don't have access to this feature on your client repository, you may need to replace these variables with actual values from XM Cloud project. To do that, you need to create a "Automation Client" from XM Cloud deploy app.
Noe you have all the details what you need. After replacing all the tokens, now we need to push your code into the client's GitHub repository.
If everything goes well, you could see the action workflow triggers itself as soon as a push happens on the configured repo branch something like below.
And you should also be able to see all the steps executed during the workflow execution.
Further Enhancement
As per the configuration .yml file pushed in earlier step, deployment will be triggered automatically every time when push happens on the branch. However, you may not want to do so every time. You may want to trigger it on demand, manually as an when needed. So, how to configure that?
Manual Trigger
We can make a very simple change in the above code snippet. In the on: section, we just need to define workflow_dispatch:
Something like.
on:
workflow_dispatch:
here is the complete .yml file content that allow you to trigger the action/workflow manually through git interface itself.
name: XM Cloud
on:
workflow_dispatch:
jobs:
deploy-production:
name: Deploy the XM Cloud Site to the Production Environment
runs-on: [ windows-latest ]
environment: production
steps:
- uses: actions/checkout@v3
- uses: actions/setup-dotnet@v2
with:
dotnet-version: '6.0.x'
- run: dotnet tool restore
- run: dotnet sitecore --help
- name: Authenticate CLI with XM Cloud
run: dotnet sitecore cloud login --client-credentials --client-id ${{ secrets.XM_CLOUD_CLIENT_ID }} --client-secret ${{ secrets.XM_CLOUD_CLIENT_SECRET }}
- name: Deploy the CM assets to XM Cloud
run: dotnet sitecore cloud deployment create --environment-id ${{ secrets.PRODUCTION_XM_CLOUD_ENVIRONMENT_ID }} --upload
- name: Authenticate default environment with CLI
run: dotnet sitecore login --ref xmcloud --client-credentials true --client-id ${{ secrets.XM_CLOUD_CLIENT_ID }} --client-secret ${{ secrets.XM_CLOUD_CLIENT_SECRET }} --cm ${{ secrets.PRODUCTION_XM_CLOUD_CM_URL }} --allow-write true
- name: Publish content changes
run: dotnet sitecore publish --pt Edge
Go back to the action tab in GitHub interface and click on actions. You should be able to see "Run workflow" dropdown.
This will initiate the deployment in XM Cloud and you should also be able to verify in XM Cloud deploy app.
