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.

Background on the Schema Extraction Process

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.

Setting up CI/CD pipeline with Github Actions

Details the setup of a CI/CD pipeline using Github Actions.

Setting up CI/CD pipeline with Azure DevOps

Details the setup of a CI/CD pipeline 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.

Discussion on the Provided Example

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. Replace ApiSecret with ApiKey if you're using the deprecated API key setting instead.

Full Example

trigger:
- main

pool:
  vmImage: 'windows-latest'

variables:
  solution: '**/*.sln'
  buildPlatform: 'Any CPU'
  buildConfiguration: 'Release'

  vsSolutionName: DeployOnPremSite
  vsProjectName: DeployOnPremSite
  umbracoDeployTriggerDeploy: $(Build.SourcesDirectory)\$(vsSolutionName)\$(vsProjectName)\TriggerDeploy.ps1
  umbracoDeployReason: AzureDeployment

  deployApiSecret: <set in Azure Pipeline secret>
  azureSubscription: <set in Azure Pipeline variable>
  webAppName: <set in Azure Pipeline variable>
  resourceGroupName: <set in Azure Pipeline variable>
  deploySlotName: <set in Azure Pipeline variable>
  deployBaseUrl: <set in Azure Pipeline variable>

steps:
#1 NuGet Tool Install
- task: NuGetToolInstaller@1
  displayName: Install NuGet

#2 NuGet Restore
- task: NuGetCommand@2
  displayName: Restore NuGet packages
  inputs:
    restoreSolution: '$(solution)'

#3 Build the VS Solution and publish the output to a zip file
- task: VSBuild@1
  displayName: Build solution
  inputs:
    solution: '$(solution)'
    msbuildArgs: '/p:DeployOnBuild=true /p:WebPublishMethod=Package /p:PackageAsSingleFile=true /p:SkipInvalidConfigurations=true /p:DesktopBuildPackageLocation="$(build.artifactStagingDirectory)\WebApp.zip" /p:DeployIisAppPath="Default Web Site"'
    platform: '$(buildPlatform)'
    configuration: '$(buildConfiguration)'

#4 Deploy to an Azure web app slot
- task: AzureRmWebAppDeployment@4
  displayName: Deploy to web app
  inputs:
    ConnectionType: 'AzureRM'
    azureSubscription: '$(azureSubscription)'
    appType: 'webApp'
    WebAppName: '$(webAppName)'
    deployToSlotOrASE: true
    ResourceGroupName: '$(resourceGroupName)'
    SlotName: '$(deploySlotName)'
    packageForLinux: '$(build.artifactStagingDirectory)\WebApp.zip'

#5 Trigger the Umbraco Deploy extraction
- task: PowerShell@2
  displayName: Run PowerShell script
  inputs:
    filePath: '$(umbracoDeployTriggerDeploy)'
    arguments: '-InformationAction:Continue -Action TriggerWithStatus -ApiSecret $(deployApiSecret) -BaseUrl $(deployBaseUrl) -Reason $(umbracoDeployReason) -Verbose'

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.

1. 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.

1. Go to the Settings tab.

2. Choose which source and build provider to use.

   • In this case we want to choose Github.

1. Choose the Organization which you created our Github repository under.

2. Choose the repository that was set up earlier in this guide.

3. 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:

1. 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.

1. Pull down the new file and folder, so you can work with the YAML file on your local machine.

2. Configure it to work with our Umbraco Deploy installation.

When it have been configured it will look something like this:

# Docs for the Azure Web Apps Deploy action: https://github.com/Azure/webapps-deploy
# More GitHub Actions for Azure: https://github.com/Azure/actions
name: Build and deploy ASP.Net Core app to Azure Web App - Jonathan-deploy-v10
on:
  push:
    branches:
      - main
  workflow_dispatch:
jobs:
  build:
    runs-on: windows-latest
    steps:
      - name: Checkout the git repository
        uses: actions/checkout@v3
      - name: Setup dotnet 6
        uses: actions/setup-dotnet@v2
        with:
          dotnet-version: '6.0.x'
      - name: Build with dotnet
        working-directory: 'Jonathan-Deploy-V10'
        run: dotnet build --configuration Release
      - name: Publish with dotnet
        working-directory: 'Jonathan-Deploy-V10'
        run: dotnet publish -c Release -o ${{env.DOTNET_ROOT}}/myapp
        
      - name: Upload artifact for deployment job
        uses: actions/upload-artifact@v4
        with:
          name: .net-app
          path: ${{env.DOTNET_ROOT}}/myapp
  deploy:
    runs-on: windows-latest
    needs: build
    environment:
      name: 'Production'
      url: ${{ steps.deploy-to-webapp.outputs.webapp-url }}
    env:
      deployBaseUrl: https://jonathan-testing-deploy-v10.testsite.net
      umbracoDeployReason:  DeployingMySite
    steps:
      - name: Download artifact from build job
        uses: actions/download-artifact@v4
        with:
          name: .net-app
      - name: Deploy to Azure Web App
        id: deploy-to-webapp
        uses: azure/webapps-deploy@v2
        with:
          app-name: 'Jonathan-Deploy-V10'
          slot-name: 'Production'
          publish-profile: ${{ secrets.AZUREAPPSERVICE_PUBLISHPROFILE_ABC78A5A9E9FG07F87E8R5G9H9J0J7J8 }}
          package: .
      - name:  Run Deploy Powershell - triggers deployment on remote env
        shell: powershell
        run: .\TriggerDeploy.ps1 -InformationAction:Continue -Action TriggerWithStatus -ApiSecret ${{ secrets.deployApiSecret }} -BaseUrl  ${{ env.deployBaseUrl }} -Reason  ${{ env.umbracoDeployReason }} -Verbose       

We also need to add the License file and TriggerDeploy.ps1 file in an item group in the csproj file:

<ItemGroup>
<Content Include="umbraco/Licenses/umbracoDeploy.lic" CopyToOutputDirectory="Always"/>
<Content Include="TriggerDeploy.ps1" CopyToOutputDirectory="Always"/>
</ItemGroup>

As well as enabling Unattended install in the appsettings.json file so Umbraco installs automatically:

{
  "Umbraco": {
    "CMS": {
      "Unattended": {
        "InstallUnattended": true
      }
    }
  }
}

Before the build can work, we will need to set up our generated API key to work with the build server in GitHub Actions.

1. Open your Github repository.

2. Navigate to Settings.

3. Go to the Secrets tab.

4. Select "New repository secret".

5. Call the new secret "DEPLOYAPISECRET".

6. Add the API secret from the appsettings.json file (replace ApiSecet with ApiKey in the script and use the corresponding value if you're using the deprecated API key setting instead).

7. 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.