In this section we have summarised the changes to Umbraco Deploy and Deploy Contrib released in each version. Each version is presented with a link to the Deploy issue tracker showing a list of issues resolved in the release. We also link to the individual issues themselves from the detail.

If there are any breaking changes or other issues to be aware of when upgrading they are also noted here.

Release History

This section contains the release notes for Umbraco Deploy 13 including all changes for this version.

13.3.1 (November 29th 2024)

• Update documentation links in management dashboard to include major version in the URL

• Add ValidateDependenciesOnImport setting to management dashboard

13.3.0 (November 21st 2024)

• All items from 13.3.0-rc1

13.3.0-rc1 (November 13rd 2024)

• Add option to include all schema in a workspace export

• Add option to export from transfer queue

• Combine migrated grid editor with default Block Grid block configuration (set RowMinSpan and RowMaxSpan to 1 and EditorSize to medium)

• Import on startup

• Added ValidateDependenciesOnImport setting to disable dependency validation on import

• Fixed issue where content was not saved when transferring variant content with a release date

• Support flexible environments on Umbraco Cloud (remove requirement for environment types to be Development, Staging or Live)

13.2.2 (October 3rd 2024)

• Support migrating legacy Grid editor settings (config/styles) using JSON object pre-values

13.2.1 (September 17th 2024)

• Fix tree export of members by member type

• Ensure release date of invariant content is correctly transferred #233

• Parse nested JSON property values from artifact values #234

13.2.0 (August 15th 2024)

• All items from 13.2.0-rc1

• Fixed Could not create Udi node: {Id} and entity type {EntityType} exception when exporting tree nodes without children

• Fixed deploy signatures not getting cleared when members are deleted #230

• Allow members to be deployed when selected as items in a multi-node tree picker #231

• Apply ExcludedEntityTypes configuration to disk operations #232

13.2.0-rc1 (July 19th 2024)

• Add migrators to support legacy Grid layout to Block Grid migration

13.1.1 (July 11th 2024)

• Add [DisableRequestSizeLimit] attribute to UploadForImport endpoint to remove application request size limit (server/infrastructure restrictions may still apply)

• Determine missing routePath based on $routeParams to fix Export, Queue for transfer, and Partial Restore actions on items with children in a list view

• Set trashed state when processing content #223

• Improve exception message when parent cannot be found when getting artifact #216

13.1.0 (March 19th 2024)

• All items from 13.1.0-rc1

• Fixed issue with transfer of date values within Nested Content, Block List, or Block Grid properties #209

• Fixed issue where templates could incorrectly cause schema mismatch errors when running in production mode #187

• Fixed issue where importing invalid variant property data would cause a not supported variation exception #8

• Fixed deserialization issue causing problems with the compare content feature #212

• Add configuration to allow control over suspension and resumption of Examine and document cache events during Deploy operation #211

13.1.0-rc1 (March 5th 2024)

• Add IArtifactTypeResolver to allow custom type resolving when deserializing to IArtifact (used by Deploy Contrib, see PR #60)

• Add base migrators for importing legacy artifacts (used by Deploy Contrib)

• Restored ability to overwrite content properties with empty values

• Improved error UX and messaging to only show technical detail option if available

• Require a valid license when importing

• Only validate ApiKey and ApiSecret when workspaces are configured

• Explicitly register API controller endpoints

13.0.4 (February 20th 2024)

• Removed the no-longer supported "live edit" feature (Deploy on Cloud only).

• Fixed issue where the removal of a master template couldn't be deployed #201

• Ensured configuration for behavior following a "path too long" exception is respected for handling image cropper values #200

• Added configuration setting to allow hiding of version details on the settings dashboard.

• User experience and message improvements on content flow exception #202

• Fixed issue with transfer of empty values to overwrite non-empty ones.

13.0.3 (January 16th 2024)

• Added configurable option to avoid overwriting of dictionary items with empty values #191

  • For more details see the page on Deploy's settings.

• Fixed regression issue with transfer of date values.

13.0.2 (January 9th 2024)

• Fixed issue with transfer of content using language variants #193

13.0.1 (December 21th 2023)

• Fixes the display of the selected schedule date on queue for transfer.

• Fixes parsing property values within Nested Content and Block List that were previously saved by the Contrib value connectors.

• Fixed incorrectly including media files in export when 'Content files' wasn't selected.

• Add maximum file size validation to import file upload.

13.0.0 (December 14th 2023)

• All items from the 13.0.0 RCs and latest 12.2 features.

13.0.0-rc5 (December 12th 2023)

• Align with latest CMS RC.

13.0.0-rc4 (December 11th 2023)

• Add weight -100 to Deploy package migration (ensuring Deploy database tables are available before other package migrations are executed).

• Add fluent API for Deploy webhooks.

13.0.0-rc3 (November 29th 2023)

• Added optional deployment of webhooks as part of schema updates.

• Added Deploy specific webhook events.

13.0.0-rc2 (November 15th 2023)

• Exclude automatic relation type aliases (used for reference tracking) from deployment.

• Fix cyclic dependency between configuring DeploySettings and ConnectionStrings.

13.0.0-rc1 (November 6th 2023)

• Compatibility with Umbraco 13:

  • See full details of breaking changes under the version specific upgrade guide.

  • Update Richtext value connector to handle references in blocks.

Deploy Contrib

13.3.0 (October 3rd 2024)

• Migrate nested/recursive legacy pre-value property values #71

13.2.0 (August 15th 2024)

• All items from 13.2.0-rc1

13.2.0-rc1 (July 19th 2024)

• Skip empty pre-values #63

• Add Matryoshka Group Separator artifact migrator #67

• Add migrators to support DocTypeGridEditor to Block Grid migration #66

13.1.0 (March 19th 2024)

• All items from 10.2.0-rc1

13.1.0-rc1 (March 5th 2024)

• Add legacy migrators and type resolver to allow importing from Umbraco 7 in #61

13.0.0 (December 14th 2023)

• Compatibility with Umbraco 13

Legacy release notes

You can find the release notes for versions out of support in the Legacy documentation on GitHub and Umbraco Deploy Package page

Umbraco Deploy is a commercial product. You will need a valid license to use the product.

A license for Umbraco Deploy is included when hosting on Umbraco Cloud.

How does it work?

Licenses are sold per domain and will also work on all subdomains. With every license, you will also be able to configure two development/testing domains.

Example

Let's say that you have a license configured for your domain, mysite.com, and you've configured two development domains, devdomain.com and devdomain2.com.

The license will cover the following domains:

• localhost

• *.mysite.com

• www.mysite.com

• mysite.com.local

• devdomain.com

• www.devdomain.com

• devdomain2.com

• www.devdomain2.com

What does a license cover?

There are a few differences as to what the licenses cover:

A single license covers one Umbraco solution. It includes all domains hosted by the solution, all production environments (if load-balancing), and all non-production environments.

To clarify the above:

• You only need one license when you have a solution covering multiple domains- for example, www.mysite.com and www.mysite.dk - load balanced in production over multiple servers running from the same database, managed from the same backoffice instance, and with any number of non-production environments (staging, QA, etc.)

• You need two licenses if you have a web presence that consists of two separate websites hosted on different domains or sub-domains - for example, www.mysite.com and shop.mysite.com - with each of these managed as a separate Umbraco installation using their own database and backoffice in production.

Purchasing your license

You can look at the pricing, plans, features, and purchase the license on the Umbraco Deploy On-premises page.

Installing your license

Once you've configured your license with the correct domains, you are ready to install the license on your Umbraco installation.

For Umbraco Deploy On-Premise 12 and above, this will be a key provided to you when taking out your subscription to the product. It should be added to your configuration at the key Umbraco:Licenses:Umbraco.Deploy.OnPrem.

For example, in appsettings.json:

  "Umbraco": {
    "CMS": {
      ...
    },
    "Licenses": {
      "Umbraco.Deploy.OnPrem": "<your license key>"
    },
    "Deploy": {
       ...
    }

"Umbraco_Deploy_OnPrem": "YOUR_LICENSE_KEY"

Umbraco Cloud projects use a license file placed in the /umbraco/Licenses folder that is provided automatically when your project is created.

Validating the license

On start-up and on a schedule, Umbraco running Deploy On-premise will call out to a service. It will pass the configured license key to determine its validity. The response triggers a notification that the Umbraco Deploy will handle. It will amend the available functionality as appropriate to a valid, invalid or expired license.

You can view the status of the Umbraco Deploy On-premise license in the backoffice. This is available via the Settings section, listed along with any other products using the same licensing service:

When and how to configure an UmbracoApplicationUrl

The website domain used for validating the license is determined from your Umbraco instance. To ensure the correct one is used, you can configure the UmbracoApplicationUrl.

If you are running on a single domain for both your frontend and backend environments, it's not necessary to configure a UmbracoApplicationUrl.

If you have different domains for your frontend and backend, then it's advised that you configure an UmbracoApplicationUrl set to your backoffice URL. This helps the licensing engine know which URL should be used for validation checks. Without this configuration setting, the licensing engine will try and work out the domain to validate from the HTTP request object. This can lead to errors when switching between domains.

An UmbracoApplicationUrl can be configured in your appSettings.json file like so:

{
    "Umbraco": {
        "CMS": {
            "WebRouting": {
                "UmbracoApplicationUrl": "https://admin.my-custom-domain.com/"
            }
        }
    }
}

See the Fixed Application URL documentation for more details about this setting.

Validating a license without an outgoing Internet connection

Some Umbraco installations will have a highly locked down production environment, with firewall rules that prevent outgoing HTTP requests. This will interfere with the normal process of license validation.

On start-up, and periodically whilst Umbraco is running, the license component used by Umbraco Deploy will make an HTTP POST request to https://license-validation.umbraco.com/api/ValidateLicense.

If it's possible to do so, the firewall rules should be adjusted to allow this request.

If such a change is not feasible, there is another approach you can use.

You will need to have a server, or serverless function, that is running and can make a request to the online license validation service. That needs to run on a daily schedule, making a request and relaying it onto the restricted Umbraco environment.

To set this up, firstly ensure you have a reference to Umbraco.Licenses version 13.1 or higher. This will be the case if you are running Umbraco Deploy 13.1 or higher. If you are on an earlier version, you can add a direct package reference for Umbraco.Licenses.

Then configure a random string as an authorization key in configuration. This is used as protection to ensure only valid requests are handled. You can also disable the normal regular license checks - as there is no point in these running if they will be blocked:

  "Umbraco": {
    "Licenses": {
      "Umbraco.Deploy.OnPrem": "<your license key>"
    },
    "LicensesOptions": {
      "EnableScheduledValidation": false,
      "ValidatedLicenseRelayAuthKey": "<your authorization key>"
    }

Your Internet enabled server should make a request of the following form to the online license validation service:

POST https://license-validation.umbraco.com/api/ValidateLicense
{
    "ProductId": "Umbraco.Deploy.OnPrem",
    "LicenseKey": "<your license key>",
    "Domain": "<your licensed domain>"
}

The response should be relayed exactly via an HTTP request to your restricted Umbraco environment:

POST http://<your umbraco environment>/umbraco/licenses/validatedLicense/relay?productId=<product id>&licenseKey=<license key>

A header with a key of X-AUTH-KEY and value of the authorization key you have configured should be provided.

This will trigger the same processes that occur when the normal scheduled validation completes ensuring your product is considered licensed.

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.

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

Details the setup of a CI/CD pipeline using Azure DevOps.

In this troubleshooting section, you can find help to resolve issues that you might run into when using Umbraco Deploy.

If you are unable to find the issue you are having, then please reach out to our friendly support team at contact@umbraco.com.

Schema mismatches

When transferring or restoring content between two Umbraco Deploy environments, you might run into Schema mismatch errors. For more information on how to resolve schema mismatch issues, see the Schema Mismatches article.

Umbraco Deploy maintains a cached set of signatures that represent each schema and content item. They are used when transferring or restoring content between environments to aid performance.

If having resolved schema mismatches you still have reports of errors, it might be that the signatures are out of date. In other words, Deploy is using a cached representation of an item that no longer matches the actual item stored in Umbraco.

This should not be necessary in normal use, but can occur after upgrades. If you have this situation, you can clear the cached signatures in both the upstream and downstream environments. You do this via the Clear Cached Signatures operation available on the Settings > Deploy dashboard:

Slow responses or timeouts when restoring or transferring

When transferring or restoring content between environments, Deploy needs to ensure that all related items are updated together. It also checks that any schema dependencies an item has also exist in the target environment. When a large amount of content is selected for transfer or restore, this process of determining all the dependent items can take some time.

In some cases, a hard limit imposed by the Cloud hosting platforms such as Azure, used by Umbraco Cloud, can be reached.

If you find the process slow or reporting a platform timeout, there are a few options you can take.

Consider partial restore

If restoring, you can choose to pull down a smaller set of content via the partial restore feature. With this you select an item in the remote environment to restore. You can select to include child items. Any items related to the selected ones, for example via content or media pickers, will also be restored.

Consider import/export

In addition to transferring content via the backoffice, it is possible to move both content and schema between environments via Deploy's import/export feature. With this, a selection of Umbraco data can be exported from one environment to a .zip file. That file can then be imported into another environment.

As this process requires less inter-environment communication, it's possible to transfer much larger amounts of content without running into the hard platform limits.

Read more about the import/export feature here.

Review timeouts

Firstly, you can review and update the timeout settings available with Deploy. Increasing these from the default values may help, but won't necessarily resolve all issues. This is because, as noted, some timeouts are fixed values set by the hosting environment.

Use batch configurations

There are two places where Deploy operations can be batched. This allows breaking up of a single, long process into multiple, smaller ones. By doing this it's possible to complete each smaller operation within the platform imposed timeout.

For transfers to upstream environments

If transferring items from a downstream environment to an upstream one, it's possible to configure a batch size. With this in place, transfers will be batched into separate operations, allowing each single operation to complete before any hosting environment-enforced timeout.

This will take effect only for transfers to upstream environments and when multiple items are selected in the backoffice. An example is the selection of a single media folder containing many files.

For processing of a Deploy "package"

A package is an ordered structure containing all the items selected for a Deploy operation, plus all the determined dependencies and relations. The processing of this package in the target environment can also be batched via a configuration setting.

When set, if the number of items determined for the package exceeds the batch size, the processing will be chunked into batches.

Ensure signatures are pre-cached

For transfer or restore operations, it's worth ensuring Deploy's cached signatures are fully populated in both the upstream and downstream environments. This can be done via the Set Cached Signatures operation available on the Settings > Deploy dashboard:

The process make take a few minutes to complete if you have a lot of content or media in your installation. Information is written to the log indicating the signatures calculated for each entity type.

Now the checks Deploy has to do to figure out the items and dependencies to process will complete much more quickly.

Modify the checksum calculation method for media files

Deploy will do comparisons between the entities in different environments to determine if they match and decide whether to include them in the operation. By default, for media files, a check is made on a portion of the initial bytes of the file.

If a lot of files need to be checked, this can be slow, and a faster option is available that uses the file metadata. The only downside of changing this option is a marginally increased chance of Deploy considering a media file hasn't changed when it has. This would omit it from the deployment.

This option can be set in configuration.

Consider disabling cache refresher notifications

When a Deploy operation completes, cache refresher notifications are fired. These are used to update Umbraco's cache and search index.

In production these should always be enabled, to ensure these additional data stores are kept up to date.

If attempting a one-off, large transfer operation, before a site is live, you could disable these via a configuration setting. That would omit the firing and handling of these notifications and remove their performance overhead. Following which you would need to ensure to rebuild the cache and search index manually via the backoffice Settings dashboards.

Review relation types included in deploy operations

As well as transferring entities between environments Deploy will also include the relations between them. As of 10.1.2 and 11.0.1, two relation types used for usage tracking are omitted by default. These do not need to be transferred as they are recreated by the CMS as part of the save operation on the entity.

If using an earlier version, or to make further adjustments, modify the settings for relation types in configuration.

Path too long exceptions

When restoring between different media systems exceptions can occur due to file paths. They can happen between a local file system and a remote system based on blob storage. What is accepted on one system may be rejected on another as the file path is too long. Normally this will only happen for files with particularly long names.

If you are happy to continue without throwing exceptions in these instances you can modify the configuration. If this is done such files will be skipped, and although the media item will exist there will be no associated file.

Schema files following upgrades

When Umbraco schema items are created, a representation of them is saved to disk as a .uda file in the /data/revision/ folder. The representation is known as an artifact. It will be refreshed on further updates to represent the current state of the schema item.

Following an upgrade, it's possible the contents of the file will no longer match what would be generated by the current version. For example, if a property has been added to an artifact, this will be absent in the file. It would be added if the file was recreated following the upgrade.

This can lead to situations where Deploy continues to process a file it considers changed, even though the item represented is up-to-date. This in turn means slow updates of Umbraco schema, as Deploy is processing more files than it needs to do.

To resolve this situation, following an upgrade, it is good practice to re-save the .uda files in the "left-most" environment. This will usually be the local one, or if not using that, the Development environment. You can do this via the Export Schema To Data Files operation available on the Settings > Deploy dashboard:

The updated files should be committed to source control and deployed to upstream environments.

Umbraco Deploy is a deployment tool that helps you with the process of transferring code and data between multiple environments. Deploy can be configured for many different setups and is great for both small setups as well as large and more complex infrastructures.

With Umbraco Deploy you get to use the Umbraco Cloud Deployment technology outside of Umbraco Cloud to ease deployment between multiple Umbraco environments. This is done by connecting external hosted Umbraco projects with a local instance of your Umbraco website.

In the Umbraco Deploy documentation can read all about how to set up and work with Umbraco Deploy.

You can find articles about how to set up Umbraco Deploy on a new or an existing website, and articles about the deployment workflow.

In this article you can learn more about what it takes to get started using Umbraco Deploy. You can also get a high-level overview of how the product works.

How Umbraco Deploy works

Umbraco Deploy works by serializing non-content Umbraco items (called “Schema” items) to disk. These serialized files are located in the /umbraco/Deploy/Revision folder at the root of your website.

These items are entities like Document Types, Media Types, Data Types, etc, and these files must be committed to source control (for example Git). Umbraco Deploy works by “extracting” this serialized information back into your Umbraco installation. This is done by deployment triggers when a deployment is sent to a target environment.

For example, when working locally you might create a new Document Type. This will automatically create a new on-disk file in the umbraco/Deploy/Revision folder which is the serialized version of the new Document Type. You would then commit this file to your repository and push this change to your hosted source control (for example GitHub).

When you want this deployed to your next environment, you would trigger your CI/CD process (for example Azure DevOps or GitHub Actions). This will push the changes to your environment. Once the build deployment completes successfully, a Deployment Trigger would be executed as an HTTPS request to your target environment. All changes found in the umbraco/Deploy/Revision folder will then be extracted into the Umbraco target environment.

There are three main steps you need to go through in order to start using Umbraco Deploy on your website.

1. • Set up a repository and then install a new Umbraco project inside it.

2. • Umbraco Deploy can be installed via NuGet.

3. • Umbraco Deploy needs a CI/CD build server needs to be set up to run when you want changes to be deployed to next upstream environment

This documentation platform covers only major versions of the Umbraco Deploy since Umbraco 9+. If you are using an older version of Umbraco Deploy, you will need to go elsewhere.

The documentation for Umbraco 7 and 8 lives on .

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

Prerequisites

Ensure to first read and follow the setup guides for either new or existing projects below:

Source Control Configuration

After the Umbraco files have been committed add the following lines to the .gitignore so that they will not be picked up by Git when we are deploying.

**/media/*

# Umbraco deploy specific
**/umbraco/Deploy/deploy*

Make sure that the updates to the .gitignore file are also committed.

Installing and Configuring Umbraco Deploy

When Umbraco has been installed in a repository, we can install Umbraco Deploy in the project.

To install Umbraco Deploy, run dotnet add package Umbraco.Deploy.OnPrem from the command line or Install-Package Umbraco.Deploy.OnPrem from the package manager console in Visual Studio.

With Umbraco Deploy installed, to use it in the project you will need to create and add configuration for an API key/secret.

For improved security, it is recommended to set the ApiSecret (instead of the ApiKey) setting to a cryptographically random value of 64 bytes. Using Base64-encoding to get the string representation, will result in a value of 88 characters. For versions prior to Deploy 12 or when not using the API secret setting, the recommendation is to set the ApiKey to a randomly generated string of 64 characters.

using System;
using System.Security.Cryptography;

byte[] secret = new byte[64];
RandomNumberGenerator.Create().GetBytes(secret);
string apiSecret = Convert.ToBase64String(secret);

Console.Write(apiSecret);

$secret = [byte[]]::new(64); [System.Security.Cryptography.RandomNumberGenerator]::Create().GetBytes($secret); return [System.Convert]::ToBase64String($secret)

{
  "Umbraco": {
    "Deploy": {
        "Settings": {
            "ApiSecret": "<your API secret here>",
        }
    }
  }
}

using System;
using System.Security.Cryptography;

byte[] secret = new byte[32];
RandomNumberGenerator.Create().GetBytes(secret);

var apiKey = new StringBuilder(secret.Length * 2);
for (int i = 0; i < secret.Length; i++)
{
   apiKey.AppendFormat("{0:X2}", secret[i]);
}

Console.Write(apiKey.ToString());

$secret = [byte[]]::new(32); [System.Security.Cryptography.RandomNumberGenerator]::Create().GetBytes($secret); return -join ($secret | %{ '{0:X2}' -f $_ })

{
  "Umbraco": {
    "Deploy": {
        "Settings": {
            "ApiKey": "<your API key here>",
        }
    }
  }
}

Configuring Environments

Once the API secret has been added, it is now time to configure the environments, also in the appsettings.json file.

An example configuration with a single upstream environment file will look like this:

{
   "Umbraco": {
      "Deploy": {
         "Settings": {
            "ApiSecret": "<your API secret here>"
         },
         "Project": {
            "CurrentWorkspaceName": "Live",
            "Workspaces": [
               {
                  "Id": "efef5e89-a19b-434b-b68a-26e022a0ad52",
                  "Name": "Live",
                  "Type": "live",
                  "Url" :"https://localhost:44307"
               }
            ]
         }
      }
   }
}

The setting under Project:CurrentWorkspaceName should match the Name provided in the list of Workspaces that match the current environment. Using this Umbraco Deploy will indicate the correct current environment on the "Workspaces" dashboard.

Expected values for Type are "development", "staging" or "live". These settings are required, though strictly only for the latter is it necessary to use the specific value of "live", so other values can be used if you have more than these three environments.

You will need to generate a unique GUID for each environment. This can be done in Visual Studio:

1. Open "Tools".

2. Select "Create GUID".

3. Use the Registry Format.

4. Copy the GUID into the id value.

5. Generate a "New GUID" for each environment you will be adding to your setup.

Or by running the following PowerShell command:

[guid]::NewGuid().ToString()

The URL configured for each environment should be the root URL for the website and needs to be accessible by the other environments over HTTPS.

Validating Source Control

Once the configuration has been set up with the correct information we can now go ahead and make sure that the source control is including our files in the /umbraco/Deploy folder of our Umbraco project.

This can be done by going to the /umbraco/Deploy/Revision folder of the project and create a test .uda file, and then check in either your Git GUI or in the command line and verify whether the test file is being tracked.

We can see that the file has been created and it is being tracked by Git and we can go ahead and delete the test file.

Now that Umbraco Deploy has been installed on the project, we can go ahead and commit the files to the repository.

Do not push the files up yet as a CI/CD build server will first need to be set up and connected to our repository.

Include your Umbraco Deploy license file

Before moving on to setting up the build server, make sure that your license is included in your project.

For Umbraco Deploy On-Premise, this will be a key provided to you when taking out your subscription to the product. It should be added to your configuration at the key Umbraco:Licenses:Umbraco.Deploy.OnPrem.

For example, in appsettings.json:

  "Umbraco": {
    "CMS": {
      ...
    },
    "Licenses": {
      "Umbraco.Deploy.OnPrem": "<your license key>"
    },
    "Deploy": {
       ...
    }

"Umbraco_Deploy_OnPrem": "YOUR_LICENSE_KEY"

Umbraco Cloud projects use a license file placed in the /umbraco/Licenses folder that is provided when your project is created.

Read more about the Umbraco Deploy licensing model.

What is import and export?

The import and export feature of Umbraco Deploy allows you to transfer content and schema between Umbraco environments. Exports are made from one environment to a .zip file. And this file is imported into another environment to update the Umbraco data there.

When to use import and export

Umbraco Deploy provides two primary workflows for managing different types of Umbraco data:

• Umbraco schema (such as document types and data types) are transferred as .uda files serialized to disk. They are deployed to refresh the schema information in a destination environment along with code and template updates.

• Umbraco content (such as content and media) are transferred by editors using backoffice operations.

We recommend using these approaches for day-to-day editorial and developer activities.

Import and export is intended more for larger transfer options, project upgrades, or one-off tasks when setting up new environments.

As import and export is a two-step process, it doesn't require inter-environment communication. This allows us to process much larger batches of information without running into hard limits imposed by Cloud hosting platforms.

We are also able provide hooks to allow for migrations of artifacts (such as data types) and property data when importing. This should allow you to migrate your Umbraco data from one Umbraco major version to a newer one.

Exporting content and schema

To export content and schema, you can select either a specific item of content, or a whole tree or workspace.

When exporting, you can choose to include associated media files. Bear in mind that including media files for a large site can lead to a big zip file. So even with this option, you might want to consider a different method for transferring large amounts of media. For example using direct transfer between Cloud storage accounts or File Transfer Protocol (FTP).

If your account has access to the Settings section, you can also choose to include the schema information and related files as well.

When doing a workspace export, you also have the option to include all schema in the export (introduced in Deploy 13.3), regardless of whether it is in use by any content.

Umbraco Deploy will then serialize all the selected items to individual files, archive them into a zip file and make that available for download. You can download the file using the Download button.

After the download, you should also delete the archive file from the server. You can do this immediately via the Delete button available in the dialog.

If you miss doing this, you can also clean up archive files from the Umbraco Deploy dashboard in the Settings section.

Importing content and schema

Having previously exported content and schema to a zip file, you can import this into a new environment.

You can upload the file via the browser.

Similar to when exporting, you can choose to import everything from the archive file, or only content, schema or files.

We validate the file before importing. Schema items that content depends on must either be in the upload itself or already exist on the target environment with the same details. If there are any issues that mean the import cannot proceed, it will be reported. You may also be given warnings for review. You can choose to ignore these and proceed if they aren't relevant to the action you are carrying out.

The import then proceeds, processing all the items provided in the zip file.

Once complete or on close of the dialog, the imported file will be deleted from the server. If this is missed, perhaps via a closed browser, you can also delete archive files from the Umbraco Deploy dashboard in the Settings section.

Migrating whilst importing

It is possible to migrate schema and content whilst importing. For example, to change Data Type using Nested Content to Block List and ensure content data is imported to the correct Block Editor format.

Deploy contains base classes and implementations to handle common migrations that need to be registered in code, as explained in Import with migrations.

Migrating from Umbraco 7

The import and export feature is not available in Deploy 2 for Umbraco 7. We have though released a package to allow creating an export. This needs to be done in code and requires additional legacy migrators to be able to import into a newer version. This is explained in Migrating from Umbraco 7.

Service details (programmatically importing and exporting)

Underlying the functionality of import/export with Deploy is the import/export service, defined by the IArtifactImportExportService.

You may have need to make use of this service directly if building something custom with the feature. For example you might want to import from or export to some custom storage.

The service interface defines two methods:

• ExportArtifactsAsync - takes a collection of artifacts and a storage provider defined by the IArtifactExportProvider interface. The artifacts are serialized and exported to storage.

  • IArtifactExportProvider defines methods for creating streams for writing serialized artifacts or files handled by Deploy (media, templates, stylesheets etc.).

• ImportArtifactsAsync - takes storage provider containing an import defined by the IArtifactImportProvider interface. The artifacts from storage are imported into Umbraco.

  • IArtifactImportProvider defines methods for creating streams for reading serialized artifacts or files handled by Deploy (media, templates, stylesheets etc.).

Implementations for IArtifactExportProvider and IArtifactImportProvider are provided for:

• A physical directory.

• An Umbraco file system.

• A zip file.

These are all accessible for use via extension methods available on IArtifactImportExportService found in the Umbraco.Deploy.Infrastructure.Extensions namespace.

The following example shows this service in use, importing and exporting from a zip file on startup:

using System.IO.Compression;
using Umbraco.Cms.Core;
using Umbraco.Cms.Core.Composing;
using Umbraco.Cms.Core.Deploy;
using Umbraco.Cms.Core.Events;
using Umbraco.Cms.Core.Extensions;
using Umbraco.Cms.Core.Notifications;
using Umbraco.Deploy.Core;
using Umbraco.Deploy.Core.Connectors.ServiceConnectors;
using Umbraco.Deploy.Infrastructure;
using Umbraco.Deploy.Infrastructure.Extensions;
​
internal class ArtifactImportExportComposer : IComposer
{
    public void Compose(IUmbracoBuilder builder)
        => builder.AddNotificationAsyncHandler<UmbracoApplicationStartedNotification, ArtifactImportExportStartedAsyncHandler>();
​
    private sealed class ArtifactImportExportStartedAsyncHandler : INotificationAsyncHandler<UmbracoApplicationStartedNotification>
    {
        private readonly IHostEnvironment _hostEnvironment;
        private readonly IArtifactImportExportService _diskImportExportService;
        private readonly IServiceConnectorFactory _serviceConnectorFactory;
        private readonly IFileTypeCollection _fileTypeCollection;
​
        public ArtifactImportExportStartedAsyncHandler(IHostEnvironment hostEnvironment, IArtifactImportExportService diskImportExportService, IServiceConnectorFactory serviceConnectorFactory, IFileTypeCollection fileTypeCollection)
        {
            _hostEnvironment = hostEnvironment;
            _diskImportExportService = diskImportExportService;
            _serviceConnectorFactory = serviceConnectorFactory;
            _fileTypeCollection = fileTypeCollection;
        }
​
        public async Task HandleAsync(UmbracoApplicationStartedNotification notification, CancellationToken cancellationToken)
        {
            var deployPath = _hostEnvironment.MapPathContentRoot(Constants.SystemDirectories.Data + "/Deploy");
            await ImportAsync(Path.Combine(deployPath, "import.zip"));
​
            Directory.CreateDirectory(deployPath);
            await ExportAsync(Path.Combine(deployPath, $"export-{DateTimeOffset.UtcNow.ToUnixTimeSeconds()}.zip"));
        }
​
        private async Task ImportAsync(string zipFilePath)
        {
            if (File.Exists(zipFilePath))
            {
                using ZipArchive zipArchive = ZipFile.OpenRead(zipFilePath);
                await _diskImportExportService.ImportArtifactsAsync(zipArchive);
            }
        }
​
        private async Task ExportAsync(string zipFilePath)
        {
            using ZipArchive zipArchive = ZipFile.Open(zipFilePath, ZipArchiveMode.Create);
​
            IEnumerable<Udi> udis = DeployEntityTypes.GetEntityTypes(_fileTypeCollection, DeployEntityTypeCategories.ContentAndSchema).Select(Udi.Create);
            var contextCache = new DictionaryCache();
            string[] dependencyEntityTypes = DeployEntityTypes.GetEntityTypes(_fileTypeCollection, DeployEntityTypeCategories.All);
​
            await _diskImportExportService.ExportArtifactsAsync(_serviceConnectorFactory, udis, Constants.DeploySelector.ThisAndDescendants, contextCache, zipArchive, dependencyEntityTypes: dependencyEntityTypes);
        }
    }
}

As well as importing the content and schema directly, we also provide support for modifying the items as part of the process.

For example, you may have taken an export from an Umbraco 8 site, and are looking to import it into a newer major version. In this situation, most content and schema will carry over without issue. However, you may have some items that are no longer compatible. Usually this is due to a property editor - either a built-in Umbraco one or one provided by a package. These may no longer be available in the new version.

Often though there is a similar replacement. Using Deploy's import feature we can transform the exported content for the obsolete property into that used by the new one during the import. The migration to a content set compatible with the new versions can then be completed.

For example, we can migrate from a Nested Content property in Umbraco 8 to a Block List in Umbraco 13.

We provide the necessary migration hooks for this to happen, divided into two types - artifact migrators and property migrators.

Artifact migrators

Artifact migrators work by transforming the serialized artifact of any imported artifact, via two interfaces:

• IArtifactMigrator - where the migration occurs at the artifact property level

• IArtifactJsonMigrator - where the migration occurs at the lower level of transforming the serialized JSON itself.

Implementations to handle common migrations of Data Types from obsoleted property editors are available:

• ReplaceMediaPickerDataTypeArtifactMigrator - migrates a Data Type from using the legacy Media Picker to the current version of this property editor

• ReplaceNestedContentDataTypeArtifactMigrator - migrates a Data Type based on the obsolete Nested Content property editor to the Block List

• ReplaceGridDataTypeArtifactMigrator - migrates a Data Type based on the legacy Grid layout into the Block Grid

• ReplaceUnknownEditorDataTypeArtifactMigrator - replaces any unknown editor alias with a label

We've also made available base implementations that you can use to build your own migrations. You may need to handle the transfer of information between other obsolete and replacement property editors that you have in your Umbraco application.

• ArtifactMigratorBase<TArtifact> - migrates the artifact of the specified type

• DataTypeArtifactMigratorBase - migrates Data Type artifacts

• ReplaceDataTypeArtifactMigratorBase - migrates a Data Type from one property editor to another

• ArtifactJsonMigratorBase<TArtifact> - migrates the JSON of the specified artifact type

• ReplaceGridDataTypeArtifactMigratorBase - migrates a Data Type based on the legacy Grid layout into the Block Grid

Property migrators

Property migrators work to transform the content property data itself. They are used in the Deploy content connectors (documents, media and members) when the property editor is changed during an import:

Again we have an interface:

• IPropertyTypeMigrator

Implementations for common migrations:

• MediaPickerPropertyTypeMigrator

• NestedContentPropertyTypeMigrator

• GridPropertyTypeMigrator

And a base type to help you build your own migrations:

• PropertyTypeMigratorBase

• GridPropertyTypeMigratorBase

Registering migrators

Migrators will run if you have registered them, so you can enable only the ones needed for your solution.

You can do this via a composer, as in the following example. Here we register two of the migrators shipped with Umbraco Deploy:

Import and migration flow

When an import is started, the following happens:

1. Artifact signatures are read from the import provider (using IArtifactImportProvider.GetArtifactSignatures()).

2. The artifact signatures are sorted based on dependencies with Ordering enabled (ensuring dependent items are processed in the correct order, like parent items before children and data types before document types).

3. For each artifact signature:

   1. Check whether the entity type is allowed to be imported.

   2. Publish an ArtifactImportingNotification (cancelling will skip importing the artifact).

4. Publish a ValidateArtifactImportNotification:

   • Deploy adds a default handler (ValidateArtifactImportDependenciesNotificationHandler) to validate whether all dependencies are either in the import or already present in the current environment. It emits warnings for missing content artifacts, missing or different artifact checksums and errors for missing schema artifacts.

   • The import fails on validation errors or 'soft' fails on warnings if the WarningsAsErrors import option is set.

5. Create a Deploy scope and context (containing the 'owner' user for auditing purposes and cultures to import, in case the user doesn't have edit permissions for all languages).

6. For each artifact signature:

   1. Create a (readonly) Stream for the artifact (using IArtifactImportProvider.CreateArtifactReadStream(Udi)).

   2. Deserialize the artifact into a generic JSON object (JToken).

   3. Parse the __version and __type properties and resolve the artifact type (using IArtifactTypeResolver).

   4. Migrate the JSON object (using IArtifactJsonMigrator).

   5. Deserialize the JSON object into the artifact type.

   6. Migrate the artifact (using IArtifactMigrator).

   7. Initialize artifact processing (using IServiceConnector.ProcessInit(...)) and track deploy state with next passes.

7. For each next process pass (starting at the lowest initial next pass):

   1. Process artifact (using IServiceConnector.Process(...)).

   2. During processing: service connectors for content, media and members migrate property type values if a property editor alias has changed (using IPropertyTypeMigrator).

   3. When no next pass is required (the deploy state returns -1 as next pass):

      1. Publish an ArtifactImportedNotification.

      2. Report the import process (using IProgress.Report(...)).

8. The Deploy scope is completed, causing all scoped notifications to be published to handlers implementing IDistributedCacheNotificationHandler) and completing the import.

Details of Specific Migrations

Umbraco Deploy ships with migrators to handle the conversion of core property editors as they have changed, been removed or replaced between versions.

Grid to Block Grid

The Grid editor introduced in Umbraco 7 can still be used in version 13 but has been removed from Umbraco 14. Its functionality is replaced with the Block Grid editor.

With Deploy migrators we have support for migrating Data Type configuration and property data between these property editors.

You can configure the default migration with the following composer:

These implementations make use of the following conventions to migrate the data:

• ReplaceGridDataTypeArtifactMigrator:

  • Grid layouts are migrated to an existing or new element type with an alias based on the layout name, prefixed with gridLayout_ (this can be customized by overriding MigrateGridTemplate());

  • Row configurations are migrated to an existing or new element type with an alias based on the row name, prefixed with gridRow_ (this can be customized by overriding MigrateGridLayout());

  • Similarly, grid editors are migrated to an existing or new element type with an alias based on the editor alias, prefixed with gridEditor_ (this can be customized by overriding MigrateGridEditor()). The available editors are retrieved from the grid.editors.config.js files (can be overridden in GetGridEditors()). Each migrated grid editor will have the following property types added to the element type:

    • The media grid editor is migrated to multiple properties: the value property contains the selected media item (using Media Picker v3), altText the alternate text (using a Textbox) and caption the caption (also using a Textbox);

    • The remaining grid editors create a single value property that uses the following editors:

      • rte - the default 'Rich Text Editor', falling back to the first Umbraco.TinyMCE editor.

      • headline - the default 'Textstring', falling back to the first Umbraco.TextBox editor.

      • macro and embed grid editors are converted into rich text editors.

      • quote or any other - use falling back to the first Umbraco.TextArea editor.

    • The block label is also updated for the built-in grid editors, ensuring a nice preview is available (the WYSIWYG style previews are incompatible between these editors, so the custom views are not migrated);

  • Grid settings config and styles are migrated to a new element type with a random alias, prefixed with gridSettings_ (this can be customized by overriding MigrateGridSettings()). This is because the migration only has context about the Data Type configuration (not the actual Data Type) and multiple Data Type can potentially use the same configuration (for config and styles), so there's no predictable way to create a unique alias. The migrated settings element type will have the property types added for the config and styles:

    • Each config setting is migrated to a property with an alias based on the key, prefixed with setting_ and added below a 'Settings' property group;

    • Similarly, each style is migrated to a property with an alias based on the key, prefixed with style_ and added below a 'Styles' property group;

    • The following property editors are used for these properties based on the config/style view:

      • radiobuttonlist - a new 'Radio Button List' Data Type that uses the pre-values;

      • multivalues - a new 'Checkbox List' Data Type that uses the pre-values;

      • textstring - the default 'Textstring', falling back to the first Umbraco.TextBox editor.

      • mediapicker and imagepicker - the default 'Media Picker' (v3, single image), falling back to the first Umbraco.MediaPicker3 editor.

      • boolean - the default 'Checkbox', falling back to the first Umbraco.TrueFalse editor.

      • number - the default 'Numeric', falling back to the first Umbraco.Integer editor.

      • treepicker, treesource, textarea or any other - the default 'Textarea', falling back to the first Umbraco.TextArea editor.

• GridPropertyTypeMigrator:

  • Gets the grid layout and row configuration element types based on the alias prefix/name convention used by the Data Type artifact migrator;

  • The grid editor values are migrated to the respective properties:

    • The media grid editor converts the value to a media item with crops (based on the UDI or media path), including the focal point (although this needs to be enabled on the Data Type), alternate text and caption;

    • All other values are converted to a text value or otherwise to a JSON string;

  • If a row or cell contains settings config or styles and the corresponding block has a settings element type configured, the settings config and styles are migrated to their respective properties in a similar way, based on the property editor alias:

    • Umbraco.MediaPicker3 - removes url(' from the beginning and ') from the end of the value (commonly used as a modifier and added to the stored value), before trying to get the media item by a path.

    • All other values are returned as-is.

Given the flexibility of the grid editor and Block Grid you may want to take further control over the migration. You can do that by creating your own migrator classes, that make use of our provided base classes. You would then register your own migrators instead of the ones shipped with Umbraco Deploy in your composer.

The base classes provide the following functionality. Methods you should look to override to amend the default behavior have been noted above.

• ReplaceGridDataTypeArtifactMigratorBase - replaces the Umbraco.Grid Data Type editor alias with Umbraco.BlockGrid and migrates the configuration:

  • The number of columns is copied over.

  • Grid layouts, row configurations and grid editors are migrated to blocks:

    • If multiple grid layouts are configured or if at least one contains multiple sections or isn't the full width, each grid layout will be migrated to a 'layout block' (an element type without properties).

    • If multiple row configurations are configured or if at least one contains areas that don't allow all grid editors or has a maximum amount of items set, each row configuration is migrated to a block (this is also always done when there are multiple grid layouts, as each layout can configure allowed row configurations).

    • All grid editors are migrated to blocks (allowing a single grid editor to be migrated to multiple blocks to support DocTypeGridEditor, as that allows selecting different element types).

  • The settings config and styles are migrated to a single element type (even though each setting can define whether it's supported for rows and/or cells) and used on the blocks that are allowed.

  • Block groups are added for Layout and Content and used on the corresponding block types.

• GridPropertyTypeMigratorBase - migrates the property data from the GridValue into the BlockValue (using the Umbraco.BlockGrid layout):

  • The related Data Type is retrieved to get the configured blocks.

  • All grid control values are first migrated into their content blocks.

  • Settings config and styles for 'grid cells' are stored on the area within a row, but areas in the Block Grid can't have settings, so this is migrated into the first migrated grid control content block instead.

  • If a layout block can be found for the row configuration name, all grid controls are wrapped into that block.

  • Similarly, if a layout block can be found for the grid layout name, all items are wrapped into that block.

  • The JSON serialized BlockValue is returned.

Migrating From Doc Type Grid Editor

Ensure you are running the latest version of Umbraco.Deploy.Contrib compatible with your Umbraco major version.

In your new project, register the following migrators to add support for the import from Doc Type Grid Editor grids:

The migrators add the following behavior:

• ReplaceDocTypeGridEditorDataTypeArtifactMigrator extends ReplaceGridDataTypeArtifactMigrator and ensures any DocTypeGridEditor is migrated to blocks using the allowed element types. If the element types aren't found the default implementation will migrate to new element types.

• DocTypeGridEditorPropertyTypeMigrator extends GridPropertyTypeMigrator and ensures the Doc Type Grid Editor values are mapped one-to-one to the block item data.

Migrating from Matryoshka

We provide a migrator for this package in Umbraco.Deploy.Contrib.

This adds support for migrating Matryoshka Group Separators into native property groups. It removes the Matryoshka Data Types during import and migrates the document, media and member types. Native property groups are also changed into tabs, similarly to how they were displayed with Matryoshka installed.

To use, you register the migrators:

Source Code Example - Nested Content to Block List

As described above, the nested content to block list migration will occur register the corresponding migrator with your application.

To help write your own migrations, we share the source code of an example that ships with Umbraco Deploy. This migration converts Nested Content to Block List.

First we have the artifact migrator that handles the conversion of the configuration stored with a datatype:

And secondly we have the property migrator that handles restructuring the content property data:

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.

Umbraco Deploy uses a deployment model that relies on Git and Umbraco Deploy core technology to move your changes from one environment to another. Umbraco Deploy uses a classic "left to right" deployment model, meaning that changes are first made in the Development or local environment and then deployed to the production environment.

Deployment Approach

Umbraco Deploy uses a two-part deployment approach where we keep meta data (Document types, templates, etc) and content (Content nodes and Media) as separate parts of a deployment. In order to be able to distinguish between the two types of deployments we use the term transfer for content and media deployments and the term deploy for meta data deployments.

In summary:

1. Meta data such as Document Types, Templates, Forms, Views and config files are stored in a repository and are deployed between environments. This can be achieved using a CI/CD deployment pipeline with something like GitHub Actions or Azure DevOps.

2. Content and Media items are not stored in the repository. These need to be transferred directly from the Umbraco backoffice using the "Queue for Transfer" option. Once a content editor has all the items needed for a transfer they will use the Deployment Dashboard in the Content section to transfer the items in the queue.

Deploying meta data

In order to be able to transfer content and media, the source environment and the target environment needs to have the same setup - meaning they need to be completely in sync and have the same file structure. To achieve this you need to deploy your meta data changes to the target environment.

• Deploying from your local machine to your environments

Transfer Content and Media

Moving your content and media between your environments is done through the Umbraco backoffice. You can transfer content from one environment to another, e.g. from local to your development environment. You also have the option to restore content and media to your local or development environment from your production or staging environment.

• Transfer Content and Media

• Restore Content and / or Media

Import and Export

Another approach for transferring content and schema between environments is to use import and export. In one environment, you can export selected content, a tree, or the whole workspace to a .zip file. There are options to include related media files, schema and code files such as templates and stylesheets.

That .zip file can then be uploaded into a new environment, where it will be validated and then processed to update Umbraco.

As part of the import process, we provide hooks to allow for migrations of the imported artifacts (like data types) and property data. This should allow you to migrate your Umbraco data from one Umbraco major version to a newer one.

We recommend using the content and media backoffice transfer options for day-to-day editorial activities. Import and export is intended more for larger transfer options, project upgrades, or one-off tasks when setting up new environments.

Read more about the import and export feature.

Deploy Dashboard

In Umbraco Deploy we have included a Deploy Dashboard in the Settings section of the Umbraco backoffice to make it easier to run operations like schema deployment from data files and extract schema to data files.

When running the extract schema to data files operation, Umbraco Deploy will run an echo > deploy-export in the data folder of your project which is used to generate UDA files based on the schema in your database.

Running the schema deployment from data files operation will initiate an extraction on the environment

The extraction will end in one of two possible outcomes:

1. deploy-complete: The extraction succeeded and your environment is in good shape!

2. deploy-failed: The extraction failed - open the deploy-failed file, to see the error message.

It is also possible to see which version of Umbraco Deploy you are running, when the last operation was started and the status of the deployment operation.

The import and export features are available for Umbraco Deploy supporting Umbraco 8 and above. It's not been ported back to Umbraco 7, hence you cannot trigger an export from the backoffice or use the service.

However, you can still use this feature to help migrate from Umbraco 7 to a supported major version. This requires adding additional logic to your Umbraco 7 project to create an export ZIP archive similar to newer versions.

Exporting Umbraco 7 content and schema

You can generate an export archive in the same format as the import/export feature. This is done by adding the to your Umbraco 7 project (that already has Deploy and Deploy Contrib installed, see below). This archive can be imported into a newer Umbraco version by configuring the legacy import migrators. You can also apply additional migrators to update obsolete data types and property data into newer equivalents.

This is possible via code, by temporarily applying a composer to an Umbraco 7 project to generate the export archive on start-up:

Importing Umbraco 7 content and schema

To import this archive into a newer Umbraco project, you need to install either of these packages:

• UmbracoDeploy.Contrib 4.3 for Umbraco 8

• Umbraco.Deploy.Contrib for Umbraco 10.2, 12.1, 13.1 or later

Then you need to configure the legacy artifact type resolver and migratory.

Artifact type resolvers allow resolving changes in the type that's stored in the __type JSON property of the artifact. This is in case it moved to a different assembly or namespace (or got renamed) in a newer version. The legacy migrators handle the following changes:

• Moving the pre-values of data types to the configuration property;

• Moving the invariant release and expiration dates of content to the (culture variant) schedule property;

• Moving the 'allowed at root' and 'allowed child content types' of content/media/member types to the permissions property;

• Migrating the Data Type configuration from pre-values to the correct configuration objects and new editor aliases for:

  • Umbraco.CheckBoxList (pre-values to value list)

  • Umbraco.ColorPickerAlias to Umbraco.ColorPicker (pre-values to value list)

  • Umbraco.ContentPicker2 to Umbraco.ContentPicker (removes invalid start node ID)

  • Umbraco.ContentPickerAlias to Umbraco.ContentPicker (removes invalid start node ID)

  • Umbraco.Date to Umbraco.DateTime

  • Umbraco.DropDown to Umbraco.DropDownListFlexible (pre-values to value list, single item select)

  • Umbraco.DropDownListFlexible (pre-values to value list, defaults to multiple item select)

  • Umbraco.DropdownlistMultiplePublishKeys to Umbraco.DropDownListFlexible (pre-values to value list, defaults to multiple item select)

  • Umbraco.DropdownlistPublishingKeys to Umbraco.DropDownListFlexible (pre-values to value list, defaults to single item select)

  • Umbraco.DropDownMultiple to Umbraco.DropDownListFlexible (pre-values to value list, defaults to multiple item select)

  • Umbraco.MediaPicker2 to Umbraco.MediaPicker (removes invalid start node ID, defaults to single item select)

  • Umbraco.MediaPicker (removes invalid start node ID)

  • Umbraco.MemberPicker2 to Umbraco.MemberPicker

  • Umbraco.MultiNodeTreePicker2 to Umbraco.MultiNodeTreePicker (removes invalid start node ID)

  • Umbraco.MultiNodeTreePicker (removes invalid start node ID)

  • Umbraco.MultipleMediaPicker to Umbraco.MediaPicker (removes invalid start node ID, defaults to multiple item select)

    • Umbraco.NoEdit to Umbraco.Label

  • Umbraco.RadioButtonList (pre-values to value list, change database type from integer to nvarchar)

  • Umbraco.RelatedLinks2 to Umbraco.MultiUrlPicker

  • Umbraco.RelatedLinks to Umbraco.MultiUrlPicker

  • Umbraco.Textbox to Umbraco.TextBox

  • Umbraco.TextboxMultiple to Umbraco.TextArea

  • Umbraco.TinyMCEv3 to Umbraco.TinyMCE

• Migrating pre-value property values for:

  • Umbraco.CheckBoxList

  • Umbraco.DropDown.Flexible

  • Umbraco.RadioButtonList

The following composer adds the required legacy artifact type resolver and migrators. It also adds a custom resolver that marks the specified Document Type alias testElement as the element type. Element types are a concept added in Umbraco 8 and are required for Document Types that are used in Nested Content.

Obtaining Umbraco Deploy for Umbraco 7

Umbraco Deploy for Umbraco 7 is no longer supported and was only available on Umbraco Cloud. It was not released for use on-premise.

As such if you are looking to migrate from an Umbraco Cloud project running on Umbraco 7, you already have Umbraco Deploy installed.

If you have an Umbraco 7 on-premises website, you can use this guide to migrate from on-premises to Umbraco Cloud. Or to upgrade to a newer Deploy On-premises version. You need to obtain and install Umbraco Deploy for Umbraco 7 into your project, solely to use the export feature.

The export feature can be used without a license.

Use this guide to migrate from on-premises to Umbraco Cloud or to upgrade to a newer Deploy On-premises version.

1. Download the required dll files for Umbraco Deploy for Umbraco 7 from the following links:

1. Install Umbraco Deploy with the Contrib and Export extensions.

• Install Umbraco Deploy, Deploy.Contrib, and Deploy.Export by copying the downloaded .dll files into your Umbraco 7 site.

• When copying the files over from Umbraco Deploy you should not overwrite the following files (if you already had Umbraco Deploy installed):

• Run the project to make sure it runs without any errors

1. Update the web.config file with the required references for Umbraco Deploy:

1. Export Content.

• Export your content, schema, and files to zip.

In this article, we will show the different sections on the Deploy dashboard and how they can be used.

Deploy Status

Here you can see whether the latest deployment has been completed or failed. You can see the version of Umbraco Deploy you are running, and the last time an operation was run.

Deploy Operations

With the Deploy operations, you can run different operations in Umbraco Deploy.

Below you can read what each operation will do when run through the dashboard.

Update Umbraco Schema From Data Files

Running this operation will update the Umbraco Schema based on the information in the .uda files on disk.

Export Schema To Data Files

Running this operation will extract the schema from Umbraco and output it to the .uda files on disk.

Clear Cached Signatures

Running this operation will clear the cached artifact signatures from the Umbraco environment. This should not be necessary, however, it may resolve reports of schema mismatches when transferring content that has been aligned.

Set Cached Signatures

This operation will set the cached artifact signatures for all entities within the Umbraco environment. Use this when signatures have been cleared and you want to ensure they are pre-generated before attempting a potentially longer restore or transfer operation.

Download Deploy Artifacts

Running this operation will download a zip file with all the Deploy artifacts representing the Umbraco schema in the form of .uda files.

This operation is useful if you want to move to another Umbraco instance and migrate the data with you.

Configuration Details

Schema Comparison

The Schema Comparison table shows the schema information managed by Umbraco Deploy.

You can see a comparison between the information that is held in Umbraco and the information in the .uda files on disk.

The table shows:

• The name of the schema

• The file name

• Whether the file exists in Umbraco

• Whether the file exists

• Whether the file is up-to-date

You can also view details about a certain element by selecting "View Details".

This will show the difference between entities stored in Umbraco and the .uda file stored on disk.

As with all of our products, it is always recommended to run the latest version of Umbraco Deploy.

On the Umbraco Deploy page in the Packages page you can see what the latest version is, as well as read the changelog.

Umbraco Deploy can be upgraded via NuGet.

Open the Package Console in Visual Studio and type:

Update-Package Umbraco.Deploy.OnPrem

You will be prompted to overwrite files. You should choose "No to All" by pressing "L" .

You can open the NuGet Package Manager and select the Updates pane to get a list of available updates. Choose the package called Umbraco.Deploy.OnPrem and click update. This will run through all the files and make sure you have the latest changes while leaving the files you have updated.

Version Specific Upgrade Details

Contains version-specific documentation for when upgrading to new major versions of Umbraco Deploy.

In some cases you might not want to restore the entire content tree, but only the parts that you need. Partial restores is a feature that allows for restoring specific parts of your content instead of restoring everything.

You can use Partial Restore on

• Environments with existing content or media, and on

• Empty environments

Empty environment

In this scenario you've cloned down your environment to your local machine or setup a new environment. In both cases the new environment will have an empty Content section as well as an empty Media section.

Follow these steps to perform a partial restore to get only the parts you need:

1. Go to the Content section of the Umbraco backoffice on your environment or locally.

2. Right-click the Content Tree, or click the three dots an select Do something else.

3. Choose Partial Restore.

4. Select the environment that you would like to restore content from.

5. Click "Select content to restore" - this will open a dialog with a preview of the content tree from the environment you selected.

6. Select the content node you would like to restore.

7. Decide whether you also want to restore any child nodes below the selected node.

8. Start the restore by clicking Restore.

9. To see the restored content, reload the content tree - right-click the Content tree to find this option.