Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
The Umbraco Cloud API serves as a publicly accessible endpoint that customers can utilize to execute relevant tasks.
While its initial focus is on automating and managing deployments in Umbraco Cloud projects via the "Umbraco CI/CD Flow," future enhancements will broaden its capabilities to encompass a wider range of activities and options for Umbraco Cloud users.
For the scope of this discussion, we will concentrate solely on the endpoints associated with interactions within the Umbraco CI/CD Flow.
To integrate Umbraco Cloud into your CI/CD pipeline, you'll need to make API calls to the following endpoint https://api.cloud.umbraco.com:
/$projectId/deployments
/$projectId/deployments/$deploymentId
/$projectId/deployments/$deploymentId/package
/$projectId/deployments/$latestCompletedDeploymentId/diff
You will find relevant examples using Curl and Powershell in the sections below.
To authenticate with the Umbraco Cloud API, you'll need your Project ID and API Key. These credentials can be found in your cloud project under the 'Settings' tab, and then navigating to the 'Advanced' page.
The two elements to be used for the authentication are:
Cloud Project ID: The ID of your Umbraco project.
CI/CD API Key: Your unique identifier.
By including the API key header in your HTTP requests, you ensure secure access to your Umbraco Cloud project's resources.
For enhanced security, it's crucial to store the provided API key in a secure location. Options include a variable group in Azure DevOps or using the Secrets feature in GitHub Actions. It's important to note that each API key is tightly coupled with a specific Umbraco Cloud project and can only be used for deployments related to that project.
To authenticate your requests, include the API key in a custom HTTP header named API key.
PowerShell is a command-line shell and scripting language commonly used for automating tasks and managing configurations. It offers a versatile set of cmdlets that allow you to interact with APIs, manipulate files, and much more. Within the context of the Umbraco Cloud API, PowerShell can be employed to authenticate your requests by incorporating your unique API key.
Curl (Client URL) is a command-line tool commonly used for making HTTP requests. It's a versatile utility that allows you to interact with APIs, download files, and more. In the context of Umbraco Cloud API, curl can be used to authenticate your requests by including your unique API key.
To authenticate your API requests using curl, you'll need to include your API key in a custom HTTP header named Umbraco-Cloud-Api-Key. Here's how typical Powershell and curl commands would look for this purpose:
The Create Deployment endpoint initiates a new deployment and returns a unique deploymentId. This call serves as the initial step in the deployment process. It requires a projectId specified in the URL path and a commit message included in the request body. Essentially, this establishes the metadata necessary for initiating the deployment process. If a deployment is already underway, initiating a new one will be possible but should be avoided.
To create a deployment, you'll need to make an HTTP POST request. The request body should contain a simple JSON object with the commit message:
In Powershell, the command to initiate a new deployment would be as follows
In curl, the command to initiate a new deployment would be as follows
Part of the returned response will be the actual deploymentId. The response from the API should be an HTTP 201 Created response including a deploymentId. This ID can be stored in the pipeline variables so it can be used in later steps.
To deploy content to the Umbraco Cloud repository, you need to perform an HTTP POST request to the Umbraco Cloud API. The deployment content should be packaged as a ZIP file, which must mirror the expected structure of the Umbraco Cloud repository. This ZIP file should include all relevant files such as project and solution files, and compiled frontend code. If your setup includes a frontend project with custom elements, the build artifacts from that project should also be included in the ZIP file, and placed in the appropriate directory within the repository structure.
The HTTP POST request should be made using the multipart/form-data content type. The request URL should incorporate both the projectId and deploymentId obtained from the previous step in the API path.
The ZIP file must be structured the same way as described in the Readme.md included in all cloud projects starting from Umbraco 9. This also means if you need to change the name and/or structure of the project, you should follow the guide in the same Readme.
By adhering to these guidelines, you ensure that the uploaded content is an exact match with what is expected in the Umbraco Cloud repository, facilitating a seamless deployment process.
The purpose of packaging your content into a ZIP file is to replace the existing content in the Umbraco Cloud repository upon unpackaging. This ensures that the repository is updated with the latest version of your project files.
Make sure your ZIP archive does not contain .git folder. If you're using the .zipignore file, you can add the following line .git/* to exclude it.
Umbraco Cloud environments are using git internally. This means you should be careful about the .gitignore file you add to the package. If you have “git ignored” build js assets locally, you need to handle this so that this is not being ignored in the cloud repository.
Note: If the .gitignore file within the ZIP package does not exclude bin/ and obj/ directories, these will also be committed to the Umbraco Cloud repository.
Best Practice: If you have frontend assets your local repository's .gitignore file will most likely differ from the one intended for the Umbraco Cloud repository, it's advisable to create a separate .cloud_gitignore file. Include this file in the ZIP package and rename it to .gitignore before packaging. This ensures that only the necessary files and directories are uploaded and finally committed to the Umbraco Cloud repository.
In curl uploading the source file will be:
The response of this call will be the same deployment object (in JSON) as when creating a new deployment, but the deploymentState should now be 'Pending':
After the source file has been uploaded the deployment can be started. This will queue the deployment in the Umbraco Cloud services which will start the deployment as soon as possible. Starting the deployment is an HTTP PATCH request to the Umbraco Cloud API. projectId and the deploymentId from the previous step must be included in the path, and the deployment state set to 'Queued' in the request body.
In curl starting a deployment will be:
The response of this call will be the same deployment object (in JSON) as when creating a new deployment, but the deploymentState should now be 'Queued':
To monitor the status of a deployment—whether it's completed, successful, or otherwise — you can periodically query the 'Get Deployment Status' API. This API endpoint is an HTTP GET request to the Umbraco Cloud API, and it requires both the projectId and the deploymentId obtained from previous steps to be included in the path.
Deployments in Umbraco services can take varying amounts of time to complete. Therefore, it's advisable to poll this API at regular intervals to stay updated on the deployment's current state. For example, in a simple project, you might choose to poll the API every 15 seconds for a duration of 15 minutes. These figures are just a starting point; the optimal polling frequency and duration may differ for your specific pipeline. Based on initial experience, a 15-minute window generally suffices, but we welcome your feedback to fine-tune these parameters.
Using a curl command, polling for the deployment status would look like this:
The response from this API call will return the same deployment object in JSON format as you would receive from other API interactions. Ultimately, the deploymentState field will indicate either 'Completed' or 'Failed'. Should the deployment fail, the 'ErrorMessage' field will provide additional details regarding the issue.
The endpoint lets you retrieve a list of completed deployments. It can only list deployments that has been run through the api.
The API allows you to filter and limit the number of returned deployments using query parameters:
Skip : optional, zero or positive integer
Take : optional, zero or positive integer
Includenulldeployments : optional, boolean, defaults to true
The "skip" and "take" parameters, while optional, are always required to be used together.
With includenulldeployments set to true, you will get all completed deployments, including those that did not create any new changes in the cloud repository.
To fetch the list of deployments using a curl command, the syntax would be as follows:
The response from this API call will return an object containing a list of deployment objects. The deployment-objects are consistent with the structure used in other API responses. Deployments are listed in descending order based on their creation timestamp.
Sometimes updates are done directly on the Umbraco Cloud repository. We encourage you to not do any actual work there, but auto-upgrades and environment changes will affect the umbraco-cloud-git-repos. To keep track of such changes, you can use the 'Get Deployment Diff' API. This API endpoint will provide you with a git-patch file detailing the changes between a specific deployment and the current state of the repository. To make this API call, you'll need to include both the projectId and the deploymentId of the deployment you want to check for differences against. This is a standard HTTP GET request.
Using a curl command, fetching the potential differences would look like this:
The API response will vary based on whether or not there are changes to report. If no changes are detected, you'll receive an HTTP 204 No Content status. On the other hand, if there are changes, the API will return an HTTP 200 OK status along with a git-patch file as the content. This git-patch file can then be applied to your local repository to sync it with the changes.
Currently, the feature to transition from a development environment to staging or live, and from staging to live, is pending implementation. In the meantime, you can manage these transitions manually through the Umbraco Cloud Portal [link to relevant page in docs.umbraco.com, e.g. the section “Utilizing the Pipeline” of the new page “How To Configure A Sample CI|CD Pipeline”]..
When interacting with the Umbraco Cloud API, you may encounter various HTTP status codes that indicate the success or failure of your API request. Below is a table summarizing the possible status codes, their corresponding errors, and basic root causes to guide your troubleshooting:
Most errors have a response body that corresponds to this JSON, and the “detail” field will have a more complete error message.
| Status Code | Error | Basic Root Cause |
|---|---|---|
400
BadRequest
Check the requested path, supplied headers and query-parameters
401
Unauthorized
Check the Project Id and Api Key
404
NotFound
Usually related to the supplied deploymentId in path not being found
409
Conflict
The state of the referenced deployment is not ready for the work you are requesting
500
InternalServerError
InternalServerError
Umbraco CI/CD Flow is designed to facilitate the seamless integration of your existing CI/CD flow with Umbraco Cloud. The primary objective of this feature is to enable your automated workflows to deploy directly to Umbraco Cloud. This lets you leverage the best of both worlds: the robustness of your current CI/CD setup and the specialized hosting environment of Umbraco Cloud.
Umbraco Cloud continues to be a cornerstone in this setup, providing a cloud-based hosting solution specifically optimized for Umbraco CMS. With integration to your Continuous Integration and Continuous Deployment (CI/CD) pipeline, Umbraco CI/CD allows the inclusion of automated workflows. These automated workflows include building, testing, and deploying your Umbraco projects.
Explore the practical benefits of using Umbraco CI/CD Flow for your development and deployment needs. This solution aims to simplify your workflow, improve team collaboration, and reduce deployment time. Here are some key advantages to consider:
Seamless Integration with Existing CI/CD
Umbraco CI/CD Flow allows customers to connect their existing CI/CD pipelines to Umbraco Cloud, making the transition smoother and reducing the learning curve.
Enhanced CI/CD Features
The feature enables unique CI/CD features like PR-flows and automated tests, which are not natively available in Umbraco Cloud. This adds a layer of quality assurance and streamlines the development workflow.
Scalability and Flexibility
Umbraco CI/CD Flow allows for greater scalability and flexibility in your deployment process. You can adapt your existing CI/CD pipeline to handle larger projects or more complex workflows without having to overhaul your Umbraco Cloud setup.
Centralized Management
With Umbraco CI/CD Flow, you can centralize the management of your deployments, tests, and workflows. This makes it easier to monitor, troubleshoot, and optimize your processes, leading to more efficient and reliable deployments. Automating deployment minimizes the risc for human errors that could have a negative effect on the target environment.
Umbraco CI/CD Flow serves as a bridge between your existing CI/CD pipeline and Umbraco Cloud, enabling a more streamlined and automated deployment process. While it offers a number of advantages, there are also limitations that need to be considered. On the page 'Known Limitations and Considerations' you will find a detailed list of the pros and cons of using Umbraco CI/CD Flow.
The CI/CD process for Umbraco projects involves some key steps, from code development locally to deployment to Umbraco Cloud. The flow is generally as follows:
Code Development: Developers work on features or bug fixes in their local environments.
Customer code repository: Changes are committed and pushed to a version control system like Git in the customer's own repository.
Customer pipeline: The code is compiled and built. Tests can be run automatically in the associated pipeline to ensure code quality. Finally, the code is packaged into a zip file and prepared for deployment.
Umbraco Cloud API: The customer pipeline uploads the source packed as a zip file to Umbraco Cloud API.
Umbraco cloud repository: The deployments start which triggers the queueing of the build in Umbraco services. It then pushed the Umbraco Cloud repository to the left-most environment. And if a live environment, the website has been updated.
In a bit more detail the flow will look like this from a pipeline perspective.
To ensure you make the most of Umbraco CI/CD Flow, we suggest exploring the documentation further. Familiarizing yourself with the fundamentals is a good starting point, but delving deeper will enable you to fully harness its capabilities.
Here are three essential pages to get you started:
How to use the Umbraco Cloud API for CI/CD Flow: Gain a comprehensive understanding of how to interact with the Umbraco Cloud API for seamless deployments and management.
How To Configure A Sample CI/CD Pipeline: Follow our step-by-step guide to set up a sample pipeline, making your development and deployment process more efficient.
Known Limitations and Considerations: Familiarize yourself with the current limitations and considerations to ensure you're making the most out of Umbraco CI/CD Flow.
These resources will provide you with the knowledge and tools you need to successfully implement and optimize your use of Umbraco CI/CD Flow.
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.
As we continue to gather insights from our users, there are some known limitations and considerations to be aware of.
Format Restrictions
The packaged artifact from your CI/CD pipeline must adhere to the Umbraco Cloud API's required format, which is a zip source file. This could necessitate changes to your existing build and packaging scripts.
Workflow considerations
To ensure smooth execution of the CI/CD Flow, it is recommended to make schema changes in the . Ideally, this means the local development environment. Schema changes include changes made to Document Types, Data Types, Templates, and the like. The intention behind this principle is to prevent conflicts that could potentially arise due to simultaneous modifications made in different environments.
Additional Build Step
The flow feature adds an extra build to the deployment process. As a result, it takes longer to post to Umbraco Cloud using Umbraco CI/CD Flow compared to standard deployments.
Conflict Management
Given the necessity to avoid changes in other environments, the lack of strict coordination among multiple teams or individuals working on the same project elevates the risk of conflicts.
Direct Commits to Umbraco Git Repos: Any commits made directly to the Umbraco-git-repos will cause the process to fail.
Remote Build/Test Options: It is currently not possible to skip the first build step before committing.
Incomplete API:
The list endpoint lacks filtering capabilities.
The promotion endpoint for transitioning from dev to stage to live is not fully functional yet.
Hotfix Deployments: Direct deployments to a specific environment are not supported at this time.
Lack of Predefined Tasks: There are no Umbraco-provided Azure DevOps tasks or GitHub Actions available.
No Webhooks: Currently, there's no webhook support for real-time feedback to the pipeline; polling is the only option.
Casing Conflicts: Be cautious of casing issues, such as having a README.md file created by Azure DevOps and a Readme.md file from the default Umbraco Cloud, as this can cause conflicts in the cloud Git repository.
Documentation Alignment: We are in the process of updating our documentation to align with standard Umbraco guidelines.
Developer Experience: Plans are underway to create Umbraco-specific Azure DevOps tasks and GitHub Actions to enhance the developer experience.
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 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 .
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. 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.
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
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 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.
RestorePackagesWithLockFile in your .csproj fileIf RestorePackagesWithLockFile is used and set to true, you will experience that no changes will be made to the website. This happened even though the CI/CD deployments were completed successfully, and files were updated as expected in the Cloud repository.
The reason for this is that the KUDU deploy process fails. This process takes the newly committed files from the cloud repository and runs restore, build, and publish on the cloud environment.
To resolve this issue, remove the RestorePackagesWithLockFile to allow the deployments to go through as expected.
The mechanism to determine changes since the last deployment is not able to do so when the left-most environment has changed. This happens when you either add or remove the development environment. The responds with status 409 and the following json payload:
You will need to manually make sure that all latest changes on your left-most environment in cloud is also present in your local copy.
Once this is done you can run a new deployment, where you skip the cloud-sync step.
The sample pipelines are naively trying to apply any change coming from the generated patch file on cloud. This doesn't always work and you might see an error similar to the following:
The root cause is due to conflicts between your source and the code in the repository on Umbraco Cloud. This is usually due to one of two things:
Cloud project package(s) has been auto-upgraded, and that diff was already applied.
In both cases you have to make sure that your repository is up too speed with any changes there are in the cloud environment. You will have to resolve potential conflicts manually.
Once that has been done, you should run a new deployment without the cloud-sync step.
Ensure your GitHub repository is up-to-date with any changes in your Umbraco Cloud environment.
Locate the main.yml file in the following directory: {projectname}.github\workflows on tour local project.
Open the main.yml file in a text editor and navigate to the “jobs” section.
Comment out the entire “cloud-sync” section and the “needs: cloud-sync” under “cloud-deployment”. An example is provided in the screenshot below.
Commit the changes, and push them to GitHub. This action will trigger a build and run the pipeline.
At this point, the pipeline should execute successfully and your changes will be pushed to Umbraco Cloud. If this is the case, proceed to the next step.
Uncomment the lines you previously commented out and make a new commit. Push these changes to GitHub.
Optional: Add "[skip ci]" to the last commit message, to avoid automatically triggering the pipeline
Your pipeline should now be functioning as expected.
With a few clicks you can manually trigger a pipeline to run without the cloud-sync:
Ensure that your Azure DevOps repository is up to date with any changes in your Umbraco Cloud environment.
Find the pipeline in Azure DevOps.
Click on "Run Pipeline" in the top right corner.
Click on "Stages to run"
Uncheck the "Umbraco Cloud Sync" checkbox. Confirm on "Use selected stages".
Click on "Run" back in the "Run Pipeline" view.
As no changes were made to your pipeline, it will run as usual on next push to Azure DevOps.
We currently have a size limit set to 134217728 bytes or about ~128 MB.
Make sure that the package you are trying to upload does not contain anything unnecessary.
The service goes through all .csproj-files contained in the uploaded package, and compares that to the versions running in your left-most cloud environment. We do this to try to prevent you from downgrading the crucial Umbraco packages used by cloud.
The full error could look like this:
The error tells you which package to look for and which version is currently in your left-most cloud environment. The error also contains the problematic incoming .csproj-file and the version referenced by it.
If the incoming package references multiple packages with lower versions, the error will list each one.
We recommend aligning the package versions in your .csproj files with the higher version mentioned in the error for that package or a later version.
If you have orphaned csproj-files you should remove them or rename them. Orphaned would be backup .csproj files or files not referenced by any of the main project files nor referenced in a .sln file.
In some instances we see an issue where filename casing is causing an error.
Rename the Readme.md file in the root of your repository to something different, the file can keep the markdown-extension. Commit the change to your repository and run the pipeline.
If you want you can change the filename back to Readme.md after a successful CI/CD deployment.
In rare cases deployments fail, and the cloud infrastructure doesn't clean up correctly. This leaves behind an "updating" marker. The next time you try to deploy through your pipeline you will encounter an error.
Access KUDU on the "left-most" environment
If you only have one environment you want the live environment
If you have more than one environment, you want the development environment
Navigate to site > locks folder In there, there should be a file named updating
Remove the updating file.
Once the marker file is removed, run your pipeline again.
This happens when you use the CI/CD feature of Umbraco Cloud to deploy changes to your live environment, and later add a development environment. Your development environment will fail to boot up and will show the following error message:
This issue arises because the development environment is missing in the local umbraco-cloud.json file. To resolve this issue, follow these steps:
Navigate to Kudu in your Live environment
Select “Debug console” and choose “CMD”.
Find the umbraco-cloud.json file. Path to this file may vary depending on your setup, but the default location on cloud is C:\home\site\repository\src\UmbracoProject
Click ‘edit’ on the file and copy all its content. This content is consistent across environments, so it’s safe to do so.
Paste the copied content into the umbraco-cloud.json file in your local project and push the changes.
After completing these steps, your development environment should be correctly registered across all environments, allowing you to continue your work without any issues.
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 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 .
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. 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.
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
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 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.
While working with the project on your local machine, follow these steps to prepare the pipeline, using the .
Download the provided sample scripts as ZIP from the . Click on "Code" and then choose "Download ZIP". Then unzip it and use those files for the next steps.
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. describes how to get those values.
How to sync your Azure DevOps repository with the in Umbraco Cloud
If you experience problems with your development environment not properly booting up after deployment, .
You and your team are not following the .
For Azure DevOps, see the section.
For GitHub, see the section.
You can see an example of how you could zip your repository before uploading it, by referring to our or samples.
In order to fix this issue, you need to use to remove the leftover marker file.
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. describes how to get those values.
While working with the project on your local machine, follow these steps to prepare the pipeline, using the .
Download the provided sample scripts as ZIP from the . Click on "Code" and then choose "Download ZIP". Then unzip it and use those files for the next steps.
How to sync your GitHub repository with the in Umbraco Cloud
