Steps and examples on how to setup a build and deployment pipeline for Umbraco Deploy using GitHub Actions.
In this example we will show how you can set up a CI/CD build server using Github Actions in Azure Web Apps.
We will not cover how you can set up the site itself as this is beyond this documentation.
The following steps will take you through setting up a build server in Azure Web Apps. Go to the Azure portal and find the empty website that we have set up and want to connect to.
Go to the Deployment Center.
In the Deployment Center we can set up the CI/CD build server. With this example we are going to set up our build server by using Github Actions. It is possible to set up the build server however you want as long as it supports executing powershell scripts.
Go to the Settings tab.
Choose which source and build provider to use.
In this case we want to choose Github.
Choose the Organization which you created our Github repository under.
Choose the repository that was set up earlier in this guide.
Select which branch that we want the build server to build into.
We can see which runtime stack and version we are running, in this example we are running .NET and Version 6.0.
Once the information has been added we can go ahead and preview the YAML file that will be used for the build server:
Save the workflow.
The website and the Github repository are now connected.
If we go back to the Github repository we can see that a new folder have been created called Workflows:
Inside the folder, we find that the YAML file has been created with the default settings from the Azure Portal. The file will need to be configured so it fits into your set up.
Pull down the new file and folder, so you can work with the YAML file on your local machine.
Configure it to work with our Umbraco Deploy installation.
When it have been configured it will look something like this:
This is only an example of how you can set up the CI/CD pipeline for Umbraco Deploy. It is possible to set it up in a way that works for you and your preferred workflow.
We also need to add the License file and TriggerDeploy.ps1 file in an item group in the csproj file:
As well as enabling Unattended install in the appSettings.json file so Umbraco installs automatically:
Before the build can work, we will need to set up our generated API key to work with the build server in GitHub Actions.
Open your Github repository.
Navigate to Settings.
Go to the Secrets tab.
Select "New repository secret".
Call the new secret "DEPLOYAPIKEY".
Add the API key from the appSettings.json file.
Save the secret.
We can now go ahead and commit the configured YAML file and push up all the files to the repository.
Go to Github where you will now be able to see that the CI/CD build has started running:
The build server will go through the steps in the YAML file, and once it is done the deployment have gone through successfully:
You can now start creating content on the local machine. Once you create something like a Document Type, the changes will get picked up in Git.
When you're done making changes, commit them and deploy them to Github. The build server will run and extract the changes into the website in Azure.
This will only deploy the schema data for our local site to your website.
You will need to transfer content and media from the backoffice on your local project using the queue for transfer feature.
Steps and examples on how to setup a build and deployment pipeline for Umbraco Deploy using Azure DevOps.
In this section, we provide a full example of how Umbraco Deploy running on Umbraco 9 and above can be utilized. This can be used as a part of a build and deployment pipeline using Azure DevOps. You can use this directly or adapt it for your needs.
We have defined a single stage build and deployment pipeline, configured in YAML format. While not as visually intuitive as a drag-and-drop task list, it provides the advantage of source control management.
We then have a number of variables defined, that are used in the build configuration below. By using variables we have the ability to modify the script for use on other web applications. Some values are set in the script, and some via Azure DevOps variables or secrets.
Most tasks in the pipeline are standard steps that will be used in any .NET web application release, such as the first steps:
#1 Install of the NuGet tooling,
#2 Restore of NuGet dependencies,
#3 And the project build.
Additional steps can be added as required, for example for running automated tests.
The Umbraco Deploy license file and the schema data files will automatically be included within the build output.
The deployment part of the pipeline stage consists of two steps.
Firstly a web deployment (#4), takes the packaged build artifact and deploys it, in this case, to an Azure Web App slot.
The final step (#5) is Umbraco Deploy specific - to call a function defined in the Powershell script and trigger the extraction.
The Microsoft docs contain useful information, if you are unsure of how to set secrets for your pipeline:
Steps and examples on how Umbraco Deploy can be integrated into an automated build and deployment pipeline
Once Umbraco Deploy has been installed and the schema data has been generated, a CI/CD build server needs to be set up.
The build server will extract the changes that has been pushed to the repository into your production website that has been connected with Umbraco Deploy.
This is something that can be done in many different ways depending on where your website is hosted and your setup.
Umbraco Deploy does not require the use of any particular build or deployment tools and hence we expect that you should be able to continue using the tool or tools of your choice. Any that have support for .NET website deployments and the running of Powershell scripts. such as Azure DevOps or Github Actions, would be appropriate.
Above and beyond the normal steps of a build pipeline for a .NET web application - tasks like NuGet restore, solution build, running of tests etc. - Umbraco Deploy requires three additional steps.
The license file needs to be deployed into the target environment's umbraco/Licenses folder.
The .uda schema files that are written to disk and included in source control, need to be made available in the build artifact that is deployed to the target environment.
Once the build is complete, the extraction of the updated schema in the target environment needs to be triggered.
The first two steps will be implemented in a similar way. There will need to be a step added to the pipeline that runs after the main build of the website, to copy the license file and data files into the published build output, such that they are included in the build artifacts that are deployed to the target environment.
The third step needs to run last in the pipeline, once the built web application is deployed to the target environment. Umbraco Deploy provides a Powershell script that can be used for the purpose of triggering the extraction of the schema information and update of the target Umbraco installation.
Without a CI/CD pipeline step in place to trigger the extraction, following a deployment, the process would need to be carried out manually. This can be done by logging into the backoffice, navigating to Settings > Deploy and triggering the operation via the dashboard.
Behind the scenes what happens here is a marker file being written to disk - in the /umbraco/Deploy/ folder and with a name of deploy. It’s by monitoring this directory for a file with this name that Umbraco Deploy knows to trigger the extraction.
Umbraco Deploy also provides an HTTPS endpoint that can be called by an authenticated request. This will write the marker file, which will trigger the extraction.
Umbraco Deploy On-Premises also ships with a Powershell script, that when executed will call the endpoint, which will write the file, and which will trigger the extraction.
So while it may be possible to have the CI/CD step directly write the file or call the endpoint, so long as the build used supports running Powershell scripts this is the method we’d recommend, as it has some necessary error checking and retry logic built-in.
Details the setup of a CI/CD pipeline using Github Actions.
Details the setup of a CI/CD pipeline using Azure DevOps.
