This section provides a step-by-step guide to setting up a CI/CD pipeline in GitHub Actions using the provided sample Bash or Powershell scripts.
Before setting up the pipeline in GitHub, make sure that the following steps from the Configuring a CI/CD pipeline are done:
Pick a Cloud project
Activate CI/CD Flow
Next, you will need to define your pipeline in YAML and use it to interact with the Umbraco Cloud API.
The Umbraco CI/CD Team has created a sample pipeline for Azure DevOps.
The Scripts are provided as is. This means that the scripts will do the bare minimum for a pipeline that is utilizing the CI/CD flow.
You'll need to adapt and integrate the script to fit your pipelines to gain the ability to do deployments to your Umbraco Cloud projects.
The sample includes YAML files and custom Powershell and Bash scripts to interact with the Umbraco Cloud API.
You can get the samples for both Azure DevOps and GitHub Actions from the GitHub repository.
Please be aware that since this involves using your custom pipeline, any issues that arise will need to be resolved by you.
Go to your repositories in GitHub and click on "New".
Create a new empty repository, and note down the clone URL.
Go to the Umbraco Cloud Portal and clone your cloud project down locally. This article describes how you can find the clone URL.
Now working locally remove the Git Remote called origin, which points to Umbraco Cloud
Optionally rename branch master to main
Add a new remote called origin and pointing to the GitHub clone URL and push
Now we can move on to setting up a pipeline.
The pipeline needs to know which Umbraco Cloud project to deploy to. In order to do this you will need the Project ID and the API Key. This article describes how to get those values.
Now go to the repository in GitHub, and click on the Settings section.
Expand secrets and variables in the left-hand menu titled Security and click on Actions.
Create a repository secret called UMBRACO_CLOUD_API_KEY with the API Key value from the Umbraco Portal.
Create another repository secret with the name PROJECT_ID and the Project ID value from the Umbraco Portal.
If you want to use other names for the secrets, you need to rename the secrets variables in each of main.yml's jobs.
Now GitHub is set up with the needed information to be able to run a deployment back to Umbraco Cloud.
Next up it setting up the actual pipeline.
The sample pipelines have a job called cloud-sync. This job is responsible for checking for changes in your Umbraco Cloud project, fetching them, and applying them back to your repository. In order for this to work, you need to give the GITHUB_TOKEN write permissions to the repository during workflow runs.
This is how you can grant these permissions:
Working in your repository on GitHub, click on Settings in the top right
In the left sidebar, click on Actions and then on General
Scroll down to the Workflow permissions sections
Select the Read and write permissions
Click save
While working with the project on your local machine, follow these steps to prepare the pipeline, using the samples from the repository.
Download the provided sample scripts as ZIP from the GitHub repository. Click on "Code" and then choose "Download ZIP". Then unzip it and use those files for the next steps.
Select your preferred scripting language:
For a pipeline that uses Powershell scripts you will need the following files:
From the root folder
cloud.zipignore
From the powershell folder
Get-LatestDeployment.ps1
Get-ChangesById.ps1
New-Deployment.ps1
Add-DeploymentPackage.ps1
Start-Deployment.ps1
Test-DeploymentStatus.ps1
From the powershell/github folder
main.yml
cloud-sync.yml
cloud-deployment.yml
Do the following to prepare the pipeline:
Copy the cloud.zipignore file to the root of your repository
Make a copy of the .gitignore from your repository and call the copy cloud.gitignore
Both files should be in the root of your repository
In the bottom of the .gitignore file add the line **/git-patch.diff
Also in the root, create a folder called .github
Inside .github create two additional folders
workflows
powershell
Copy the 3 YAML files from the github folder into the workflows folder
Copy the Powershell scripts from the powershell folder to the powershell folder
Note: If you have not changed the branch to main, then in the main.yml file change the branch from mainto master.
Commit the all changes, and push to GitHub
For a pipeline that uses Bash scripts you will need the following files:
From the root folder
cloud.zipignore
From the bash folder
get_latest_deployment.sh
get_changes_by_id.sh
create_deployment.sh
upload_package.sh
start_deployment.sh
get_deployment_status.sh
From the bash/github folder
main.yml
cloud-sync.yml
cloud-deployment.yml
Do the following to prepare the pipeline:
Copy the cloud.zipignore file to the root of your repository
Make a copy of the .gitignore from your repository and call the copy cloud.gitignore
Both files should be in the root of your repository
In the bottom of the .gitignore file add the line **/git-patch.diff
Also in the root, create a folder called .github
Inside .github create two additional folders
workflows
scripts
Copy the 3 YAML files from the github folder into the workflows folder
Copy the Bash scripts from the bash folder to the scripts folder
Note: If you have not changed the branch to main, then in the main.yml file change the branch from mainto master.
Commit the all changes, and push to GitHub
The push will start a new pipeline run.
With everything set up, you may want to confirm that Umbraco Cloud reflects the changes you are sending via your pipeline.
While working on you project locally, add a new Document type.
Commit the change to main branch (or master if you did not change the branch name) and push to your repository.
The pipeline starts to run
Once the pipeline is done log into Backoffice on your left-most environment in Umbraco Cloud
Go to the Settings section and see that your new Document type has been deployed
The mentioned scripts are provided as a starting point. It is recommended that you familiarize yourself with the scripts and with documentation related to how to use GitHub Actions.
The scripts demonstrates the following:
How to sync your GitHub repository with the left-most project environment in Umbraco Cloud
How to deploy changes to the left-most project environment in Umbraco Cloud
The main.yml is the main pipeline, and is the one that will be triggered on a push to main branch. You can configure a different trigger behavior in this file.
You can add your Build and Test jobs between the cloud-sync and cloud-deployment jobs. Keep in mind that you do not need to retain the dotnet build artifact for upload later. The cloud-deployment job will take care of packaging all your source code and upload to Umbraco Cloud.
The cloud-sync.yml shows how you can sync your GitHub repository with the left-most environment of your Cloud project. In this sample, it accepts any change from the API and applies and commits it back to the branch which triggered the pipeline. However the commit does not trigger the pipeline again.
If you don't want the pipeline to commit back to the triggering branch, this is where you need to change the pipeline.
The cloud-deployment.yml show how you can deploy your repository to the left-most environment of your Cloud project. The sample shows how to prepare for deployment, request the deployment and wait for cloud to finish.
There are a couple of things here to be aware of:
We are overwriting the .gitignore file with cloud.gitignore. This is a way to accommodate your gitignore-needs when working locally. For instance you might want to ignore frontend builds, but you want them build and published to cloud.
We have a special cloud.zipignore file. This is a convenient way to tell the pipeline which files not to include when creating the zip package to send to cloud.
If you have frontend assets that needs to be build (using tools like npm/yarn or others), you should add the needed steps before Zip Source Code. This is to ensure that the fresh frontend assets will be part of the package to be sent to cloud.
Learn how to configure a CI/CD pipeline in Azure DevOps and GitHub Actions Workflows using the sample scripts provided.
You'll find example shell scripts and pipeline configurations in the Sample scripts section, covering both Azure DevOps and GitHub Actions Workflows.
Samples are provided "AS IS" to get you started. Please familiarize yourself with them, and feel free to change them to fit your needs.
Umbraco Cloud repositories are not meant to be used as source code repositories. More details here.
Once you commit your code to Cloud the build pipeline converts your C# code to DLLs and deploys it on the respective environment.
In Umbraco Cloud only C# code is built, and all frontend artifacts need to be built and committed to the repository.
You can use Azure DevOps as an external repository and with the pipelines, it will automatically keep your Azure DevOps source code repository in sync. The sync is done with the git repository of Umbraco Cloud of the development environment.
Before proceeding, you'll need an Umbraco Cloud project and a CI/CD pipeline. You will also need the required files to add to your pipeline for successful interaction with the Umbraco Cloud API.
Pick an Umbraco Cloud project, preferably with a development environment (but not a requirement)
Create a new Umbraco Cloud Project.
You can take a trial here
Create a new project in the Umbraco Cloud Portal
Use one of your existing projects.
Create a new or an existing CI/CD pipeline in Azure DevOps or GitHub Actions.
In this guide, deployments are targeted at the leftmost environment in your Umbraco Cloud setup. This means if you have a Development environment, it will be automatically selected for deployment. If no Development environment exists, the Live environment will be used.
To get started with API interactions, you'll need to obtain your Project ID and API key. If you haven't already enabled the CI/CD feature, follow these steps:
Navigate to the Umbraco Cloud Portal and select your project.
Go to Settings -> Advanced. This is where you can generate an API key and find your Project ID.
Click on "Activate CI/CD Flow" toggle to enable the feature.
The API key is tied to the specific project for which it is generated. Make sure to keep it secure in Azure or GitHub, as it will be used for all subsequent API interactions related to that project.
Below we have a couple of examples of how to set up a CI/CD Pipeline using either Azure DevOps or GitHub Actions.
Each guide describes:
How to set up a new repository in either GitHub or Azure DevOps
Get a copy of your Umbraco Cloud project into that repository
And finally how to configure a new pipeline using the provided samples
The sample pipelines are using either Bash-scripts or Powershell-scripts to facilitate communication with the Umbraco CI/CD API.
During the guides, you will have the option to choose between Powershell or Bash scripts. We recommend that you choose the scripting technology you feel most comfortable with.
Details the setup of a CI/CD pipeline using Azure DevOps.
Details the setup of a CI/CD pipeline using GitHub Actions.
This section provides a step-by-step guide to setting up a CI/CD pipeline in Azure DevOps using the provided sample Bash or Powershell scripts.
Before setting up the pipeline in Azure DevOps, make sure that the following steps from the Configuring a CI/CD pipeline are done:
Pick a Cloud project
Activate CI/CD Flow
Next, you will need to define your pipeline in YAML and use it to interact with the Umbraco Cloud API.
The Umbraco CI/CD Team has created a sample pipeline for Azure DevOps.
The Scripts are provided as is. This means that the scripts will do the bare minimum for a pipeline that is utilizing the CI/CD flow.
You'll need to adapt and integrate the script into your own pipelines to gain the ability to do deployments to your Umbraco Cloud projects.
The sample includes YAML-files and custom Powershell and Bash scripts to interact with the Umbraco Cloud API.
You can get the samples for both Azure DevOps and GitHub Actions from the GitHub repository.
Please be aware that since this involves using your custom pipeline, any issues that arise will need to be resolved by you.
Go to your repositories in Azure DevOps and click on "Create a repository".
Create a new empty repository (don't add a README and don't add a .gitignore), and note down the clone URL.
Go to the Umbraco Cloud Portal and clone your cloud project down locally. This article describes how you can find the clone URL.
Now working locally remove the Git Remote called origin, which currently points to Umbraco Cloud
Optionally rename branch master to main
Add a new remote called origin and pointing to the Azure DevOps clone URL and push
Now we can move on to setting up a pipeline.
While working with the project on your local machine, follow these steps to prepare the pipeline, using the samples from the repository.
Download the provided sample scripts as ZIP from the GitHub repository. Click on "Code" and then choose "Download ZIP". Then unzip it and use those files for the next steps.
Select your preferred scripting language:
For a pipeline that uses Powershell scripts you will need the following files:
From the root folder
cloud.zipignore
From the powershell folder
Get-LatestDeployment.ps1
Get-ChangesById.ps1
New-Deployment.ps1
Add-DeploymentPackage.ps1
Start-Deployment.ps1
Test-DeploymentStatus.ps1
From the powershell/azuredevops folder
azure-release-pipeline.yml
cloud-sync.yml
cloud-deployment.yml
Do the following to prepare the pipeline:
Copy the cloud.zipignore file to the root of your repository
Make a copy of the .gitignore from your repository and call the copy cloud.gitignore
Both files should be in the root of your repository
In the bottom of the .gitignore file add the line **/git-patch.diff
Also in the root, create a folder called devops
Copy the 3 YAML files from the powershell/azuredevops folder into the devops folder
Inside devops create an additional folder called powershell
Copy the Powershell scripts from the powershell folder to the powershell folder
Note: If you have not changed the branch to main, then in the azure-release-pipeline.yaml file change the branch from mainto master.
Commit all changes, and push to Azure DevOps
For a pipeline that uses Bash scripts you will need the following files:
From the root folder
cloud.zipignore
From the bash folder
get_latest_deployment.sh
get_changes_by_id.sh
create_deployment.sh
upload_package.sh
start_deployment.sh
get_deployment_status.sh
From the bash/azuredevops folder
azure-release-pipeline.yml
cloud-sync.yml
cloud-deployment.yml
Do the following to prepare the pipeline:
Copy the cloud.zipignore file to the root of your repository
Make a copy of the .gitignore from your repository and call the copy cloud.gitignore
Both files should be in the root of your repository
In the bottom of the .gitignore file add the line **/git-patch.diff
Also in the root, create a folder called devops
Copy the 3 YAML files from the bash/azuredevops folder into the devops folder
Inside devops create an additional folder called scripts
Copy the Bash scripts from the bash folder to the scripts folder
Note: If you have not changed the branch to main, then in the azure-release-pipeline.yaml file change the branch from mainto master.
Commit all changes, and push to Azure DevOps
The pipeline needs to know which Umbraco Cloud project to deploy to. In order to do this you will need the Project ID and the API Key. This article describes how to get those values.
Now go to the repository in Azure and click on "Set up build".
On the next screen click on "Existing Azure Pipelines YAML file"
Select main (or master if you did not change the branch name) in Branch
Select /devops/azure-release-pipeline.yaml in Path and continue
Now you are on the "Review your pipeline YAML" screen
Replace the ##Your project Id here## with the Project Id you got from Umbraco Cloud Portal
Click on "Variables"
Add the variable umbracoCloudApiKey with the value of the API Key you got from Umbraco Cloud Portal
It is recommended to handle the API Key as a secret. This can be done by ticking the "Keep this value secret" checkbox.
You can customize the names for the variables as you like, however you then need to rename the affected variables in azure-release-pipeline.yaml.
When you click on "Save and Run" your first deployment will be triggered. Which means that Azure DevOps is set up with all the needed information to be able to deploy your Cloud project back to Umbraco Cloud.
With everything set up, you may want to confirm that Umbraco Cloud reflects the changes you are sending via your pipeline.
While working on your project locally, add a new Document type.
Commit the change to main branch (or master if you did not change the branch name) and push to your repository.
The pipeline starts to run
Once the pipeline is done log into Backoffice on your left-most environment in Umbraco Cloud
Go to the Settings section and see that your new Document type has been deployed
The mentioned scripts are provided as a starting point. It is recommended that you familiarize yourself with the scripts and with documentation related to how to use Azure DevOps.
The scripts demonstrates the following:
How to sync your Azure DevOps repository with the left-most project environment in Umbraco Cloud
How to deploy changes to the left-most project environment in Umbraco Cloud
The azure-release-pipeline.yaml is the main pipeline, and is the one that will be triggered on a push to main branch. You can configure a different trigger behavior in this file.
You can add your Build and Test stage between the cloudSyncStage and cloudDeploymentStage stages. Keep in mind that you do not need to retain the dotnet build artifact for upload later. The cloudDeploymentStage job will take care of packaging all your source code and upload to Umbraco Cloud.
The cloud-sync.yml shows how you can sync your Azure DevOps repository with the left-most environment of your Cloud project. In this sample, it accepts any change from the API and applies and commits it back to the branch which triggered the pipeline. However the commit does not trigger the pipeline again.
If you don't want the pipeline to commit back to the triggering branch, this is where you need to change the pipeline.
The cloud-deployment.yml shows how you can deploy your repository to the left-most environment of your Cloud project. The sample shows how to prepare for deployment, request the deployment and wait for cloud to finish.
There are a couple of things here to be aware of:
We are overwriting the .gitignore file with cloud.gitignore. This is a way to accommodate your gitignore-needs when working locally. For instance you might want to ignore frontend builds, but you want them build and published to cloud.
We have a special cloud.zipignore file. This is a convenient way to tell the pipeline which files not to include when creating the zip package to send to cloud.
If you have frontend assets that needs to be built (using tools like npm/yarn or others), you should add the needed steps before Zip Source Code. This is to ensure that the fresh frontend assets will be part of the package to be sent to Umbraco Cloud.
