When you create an Umbraco Cloud project, the project URLs are based on the name of your project.

Let's say you have a project named Snoopy. The default hostnames will be:

• Umbraco Cloud Portal - www.s1.umbraco.io/project/snoopy

• Live site - snoopy.euwest01.umbraco.io

• Development environment - dev-snoopy.euwest01.umbraco.io

• Staging environment - stage-snoopy.euwest01.umbraco.io

The hostnames contain the region on which your project is hosted. Currently, there are four options available when choosing a region for your Umbraco project:

• West Europe (euwest01),

• East US (useast01),

• South UK (uksouth01), and

• Australian East (aueast01)

To access the backoffice, add /umbraco at the end of the Live, Development, or Staging URL.

Domains

To add and manage your hostnames on Umbraco Cloud, follow the steps below:

1. Go to your project on Umbraco Cloud.

2. Go to Configuration in the side menu.

3. Click on Hostnames in the menu.

4. Click Add new hostname to add a new hostname.

Ensure that the hostname you are binding to your Umbraco Cloud environment has a DNS entry that resolves to the Umbraco Cloud service. The DNS settings can either use a CNAME or an A & AAAA record:

• CNAME: Usually used for domains with "www" in the URL.

This is recommended to use, if possible, as the record is not changed as often as A & AAAA IPs are. When setting up a CNAME it needs to point to dns.umbraco.io.

• A & AAAA records: Are usually used for the Apex domain (without "www" in the URL).

It needs to be created at the root of your domain.

• A-records to either or both IPv4 addresses:

  • 162.159.140.127

  • 172.66.0.125

• AAAA records to either or both IPv6 addresses (to support IPv6 connectivity):

  • 2606:4700:7::7d

  • 2a06:98c1:58::7d

Check with your DNS host or hostname registrar regarding configuration details for your Hostnames.

To specify the hostname for each root node using a multisite setup, follow these steps:

1. Go to the Backoffice of the project.

2. Right-click the root content node.

3. Select Culture and Hostnames.

4. Click Add New Domain in the Culture and Hostnames window.

5. Enter your Domain name and select the Language from the drop-down list.

1. Click Save.

Using special characters

Umbraco Cloud supports Internationalized Domain Names (IDN) allowing you to configure domain names including special characters.

When using an IDN direct access to the Umbraco backoffice from that domain is unavailable. If you have configured måneskin.dk as a domain, you cannot access the backoffice using måneskin.dk/umbraco. The backoffice will still be accessible using the default Cloud URL (maaneskin.euwest01.umbraco.io/umbraco), or from other domain names that do not include special characters.

Automatic Transport Layer Security (TLS)

All hostnames added to an Umbraco Cloud project's environment will get a TLS (HTTPS) certificate added, by default. The certificate is issued by Cloudflare and valid for 90 days after which it will be automatically renewed. Everything around certificates and renewals is handled for you and you only need to ensure the DNS records are configured according to our recommendations above.

Is your Domain hosted on your own Cloudflare account?

Cloudflare is a popular DNS provider, which offers a variety of different services to improve performance and security. We also use it for DNS and Hostnames on Umbraco Cloud.

When adding a hostname to your project hosted on Umbraco Cloud, using your own Cloudflare account the process is slightly different.

1. Set Proxy Status to DNS Only when creating a CNAME or A-record for your hostname in Cloudflare.

2. Change Proxy Status to Proxied once your hostname is Protected on the Hostname page for your Cloud project. Also, make sure the website is accessible through the hostname.

The above is primarily relevant when you need to use specific Cloudflare services like Page Rules, Workers, and so on.

Using Certificate Authority Authorization (CAA) for your domain?

This is necessary because Google Trust Services is the Certificate Authority for the certificates issued on Umbraco Cloud.

CAA records can be set on the subdomain, but it's not something that is commonly used. If there’s a CAA record at, e.g., app.example.com, you’ll need to remove or update it. If you want to use wildcards and allow certificates for any subdomain, the CAA record should look like this:

On the Professional and Enterprise plans, you can manually add your certificate to your project and bind it to one of the configured hostnames.

Using your Web Application Firewall (WAF) on Umbraco Cloud

If you need to use WAF in front of your Umbraco Cloud website this section will highlight some of the common configurations needed.

In most cases, you need to ensure that the WAF and Umbraco Cloud are using the same certificate on the specific hostname. Custom certificates are a plan-specific feature on Umbraco Cloud, so make sure that you have access to upload certificates.

• Make sure the hostname is pointing to Umbraco Cloud (dns.umbraco.io).

• Certificate issued for the actual hostname. A custom certificate is required for a WAF hostname.

When configuring the hostname and certificate on Umbraco Cloud it will be necessary to validate the hostname using a TXT record. This is needed because in most cases the WAF will hide that the website is running on Umbraco Cloud. This means that the usual domain ownership verification cannot be performed. This same approach can also be used to configure a hostname before updating the DNS for the hostname.

Adding a hostname on a Cloud project is possible before a DNS change. It can take up to approx. 14 days before it's removed. That means that you have 14 days to add a TXT record in your DNS settings.

Reach out to support and they will assist you with the details needed to be in the TXT record. We will first be able to see what you need to add to the TXT record when you have added the hostname.

When that is added it should work immediately.

Learn more about best practices for working with rewrite rules on Umbraco Cloud projects.

When working with an Umbraco Cloud project, you can handle a lot of the project configuration directly in the Umbraco Cloud Portal. You can manage the following configurations from the left-side menu:

Overview

Environments

See an overview of your environments for your project as well as access the frontend, backend, or clone down the environment.

Team

See who is added to your project, add new Team members, backoffice users and technical contacts, and pending invites.

Summary

You can view the Summary of your Umbraco Cloud project in the overview menu under Summary.

Edit team

Manage the team members and user permissions on your project. You can also view the backoffice user groups for each team member, view pending project invites, and manage Technical contacts for your project.

Insights

Project History

On the project history page, you can see a history of activities that have happened on your projects.

Availability & Performance

You can see metrics related to the overall health and performance of the Azure app service hosting the live environment of your solution.

Usage

On your Umbraco Cloud project, it is possible to see the usage of Custom Domains, Media Storage, Content Nodes, and Bandwidth for the project. You can also check if it is using above or below the allowed amount for the plan that your project is on.

Configuration

Connection details

Find connection details to your Umbraco Cloud databases. You need to allow your IP to connect to the databases with your local machine.

Automatic Upgrades

We handle minor and patch upgrades for the Umbraco components used by Umbraco Cloud, so you don't have to. From the Automatic Upgrades page, you can control if you want to opt in or out of automatic minor upgrades.

New projects are opt-in by default.

CDN Caching and Optimization

Manage CDN Cache settings for your project. You can modify default settings, which apply to all hostnames added to the current Project. Alternatively, you can set up specific settings per hostname, if you want to have different settings for certain hostnames.

Hostnames

Binding hostnames to your Umbraco Cloud project is done from the Hostnames section in the Settings menu on the Umbraco Cloud Portal.

Certificates (Only available on Professional or Enterprise plan)

If you have your own custom certificate, you can upload and bind it to your custom hostnames. This can be done instead of using the TLS: Transport Layer Security (HTTPS) certificates provided by the Umbraco Cloud service.

Webhooks

It is possible to configure a deployment webhook on your environments on Umbraco Cloud projects. This will be triggered upon successful deployments, you can configure where you would like information about the deployment to be posted.

Advanced

Manage Advanced settings for your project from the Settings menu:

• CI/CD Flow

• Enable static outbound IP addresses for projects on a Standard, Professional, or Enterprise plan.

• Enable IIS logging for each of your environments. The log files can be accessed through kudu in C:\home\LogFiles\http. There is a rolling size limit on the log files of 100 MB. Once the limit is reached, the oldest log files will be overwritten by new ones.

• Enable loading of a client certificate from the file system.

• Change .NET framework runtime for your Umbraco installation for each environment of your cloud project.

Backups

With this setting, it is possible to create a database backup of one or more of your cloud environments.

Security

Public access

You can deny access to your project with the Public access setting.

Users who are not part of the project or whose IP has not been allowed will not be able to access the project.

You can disable/enable it with one click on the Public access page.

Access to manage Public access requires your project to be on the Standard plan or higher.

Transport Security

Manage transport security settings for your project. You can configure certain transport security options for all hostnames or specific hostnames within your project.

Secrets Management

If your Umbraco Cloud project uses sensitive information such as API keys, encryption keys, and connection strings, it is recommended to store these as secrets.

Management

Upgrade Plan

You can upgrade your project to a Standard or a Professional plan, from the Settings menu, depending on your needs. The option is not available if you are already on the specific plan or if you are running in Trial mode.

Rename project

You can rename your Umbraco Cloud project from the Management tab in the menu.

Renaming the Project file and folder

You can rename your project from the Rename Project section in the Settings menu on the Umbraco Cloud Portal. When you rename a project, the default hostnames and clone URLs assigned to the project are updated to match the new project name. You can also rename your project files and folders locally.

Dedicated Resources

You can change your Umbraco Cloud project to run in a dedicated setup with additional computational resources compared to the shared setup. You can choose between the different dedicated options depending on the number of resources you will need for your project.

Delete Project

You can delete your Umbraco Cloud project from the Settings menu. Deleting your Umbraco Cloud project is permanent - all data, media, databases, configuration, setup, and domain bindings are removed in the process.

Dedicated Resources is a feature on Umbraco Cloud that gives you the option to move your project to a dedicated server. You can choose between a number of dedicated options depending on the amount of resources you will need for your project.

In this article, you can read about how to move your Umbraco Cloud project to dedicated resources. You can also find information about what you need to be aware of before doing so.

Before you move your project to dedicated resources

Before you decide to move your Umbraco Cloud project, you need to consider a few things:

• Umbraco Cloud offers dedicated resources for Starter, Standard, and Professional plans. You can choose among one dedicated option for projects on a Starter plan, two dedicated options for a Standard plan project, and three dedicated options for a Professional plan project.

• Moving from a shared resource to a dedicated resource will change the outgoing IP of the project. If your solution has an external service that requires whitelisting the outgoing IP, we advise you to enable the static outbound IP feature for your project and share that static outbound IP address with the third party. The static outbound IP address will not change when moving from a shared resource to a dedicated resource. For more info on static lease visit the documentation for external services.

How to move from shared to dedicated

The first step in moving to a dedicated resource is to access your project in the project overview at Umbraco.io.

• Find and select the project that you want to move to dedicated resources.

• Select Dedicated Resources from the Management menu:

• There are currently three dedicated options for you to choose from the Professional plan, two dedicated options from the Standard plan, and one dedicated option from the Starter plan. For each of the dedicated options, you will find its name, the memory and CPU cores, and the price per month.

• By hitting the "Upgrade" button on your dedicated option of choice and confirming this, you will be redirected to the project page where you will be notified when the move to a dedicated resource has been completed.

How to move from dedicated to shared

Moving away from dedicated resources and back to a shared plan can be done from the Dedicated Resources page.

• By hitting "Downgrade to shared" and confirming your choice, you will be redirected to the project page where you will be notified when the move back to a shared resource has been completed.

• Your Cloud project is now back on a shared resource.

Frequently asked questions

Wondering what happens when you move your environment to a dedicated server? Below you can find a list of the most frequently asked questions including answers.

Will it move all the environments to the dedicated server?

You can choose to only move your live environment to the dedicated server.

How will the resources be split between the environments?

All environments on the project moved to dedicated will share the resources of the dedicated server.

Will the customer be able to work on the project during the move?

It will not be possible to work on the project while it is being moved to the dedicated server. The move takes a couple of minutes, and during that time the backoffice will not respond as usual.

Will the environments be moved at the same time or one by one?

All environments that have been selected to be moved, will be moved simultaneously.

Will the live environment be unavailable while the Project is moved?

There will always be an active live environment that continues to serve requests and be online during the move operation. When the moved live environment is ready and responding to requests, the hostnames will be switched to point to the moved environment.

If you have any other questions regarding dedicated resource, feel free to reach out to Umbraco Support.

After adding hostnames to your project, it's possible to configure Content Delivery Network (CDN) Caching. This can be done for all or specific hostnames within your project.

These caching options all relate to the traffic that goes through your hostname from the origin (Umbraco Cloud) to the end-user i.e. the traffic of your website and assets from the webserver to the browser.

The options that are currently available are:

• Enable Cache (default: On)

• Cache TTL (default: 120 minutes)

• Cache Everything (default: off)

When a new hostname is added to a Project, the default settings will be applied. However, you can change the default settings for your project, so that the new hostnames will get the settings you have chosen. This also means that if you enable caching in the default settings and add a new hostname, that caching will be enabled for that new hostname.

Caching Explained

When Caching is enabled on your project it means that static assets like CSS and images are going to be cached in the Content Delivery Network (CDN) used by Umbraco Cloud. How assets are cached is up to you, as you can control it through 'cache-control headers'.

By default, Umbraco Cloud will enforce a minimum Time to Live (TTL) based on the Plan of your Umbraco Cloud Project, which means that assets cannot be cached for a shorter period than what your Plan allows. You can always choose a longer duration, especially, if you don't expect your assets to change.

These files types are cached as static assets through the CDN: '7z', 'csv', 'gif', 'midi', 'png', 'tif', 'zip', 'avi', 'doc', 'gz', 'mkv', 'ppt', 'tiff', 'zst', 'avif', 'docx', 'ico', 'mp3', 'pptx', 'ttf', 'apk', 'dmg', 'iso', 'mp4', 'ps', 'webm', 'bin', 'ejs', 'jar', 'ogg', 'rar', 'webp', 'bmp', 'eot', 'jpg', 'otf', 'svg', 'woff', 'bz2', 'eps', 'jpeg', 'pdf', 'svgz', 'woff2', 'class', 'exe', 'js', 'pict', 'swf', 'xls', 'css', 'flac', 'mid', 'pls', 'tar', 'xlsx'.

If you want to disable caching on certain types of static assets, you can use a 'no-cache' cache-control header, which will be respected by the caching strategy in the CDN. You can utilize an outbound rewrite rule to add such a cache-control header to the request.

The following example adds a cache-control header with 'no-cache' as the value when the requested Url contains a PDF file:

<rewrite>
    <outboundRules>
        <rule name="Set Cache-Control - No-Cache PDF">
            <match serverVariable="RESPONSE_Cache_Control" pattern=".*" />
            <conditions>
                <add input="{REQUEST_URI}" pattern="\.(pdf)$" />
            </conditions>
            <action type="Rewrite" value="no-cache"/>
        </rule>
    </outboundRules>
</rewrite>

Cache Everything

When Cache Everything is enabled, everything including the webpage is cached in the CDN. So, in addition to static assets, the webpage will also be cached and served from the CDN instead of loading from the origin.

When using Cache Everything you should use a Cache TTL, which matches the Editor's expectations of when the webpage is refreshed with a new version loaded from the origin. As an example, choosing a Cache TTL of 2 hours means that the webpage will be served from the cache for 2 hours and then it will be refreshed with a copy from the origin. If Editors make changes every 30 minutes, they will have to wait at least two hours until they can see the changes on the website.

Purge Caching

When assets are cached for a long time and you need to refresh them, you can choose to purge the CDN cache to remove everything from the cache and force a refresh. This can be useful after having deployed changes to JS and CSS files, which are cached in the CDN. If you have caching enabled, you can purge the cache in the Purge Cache section at the bottom of the page.

Cache purging is done per hostname and it can take up to 30 seconds before assets are completely gone from the CDN, as it's refreshed globally.

By default, all hostnames are selected, but you can choose to purge specific hostnames from the environments in your Umbraco Cloud project.

Purging the cache is a heavy operation, so there is a constraint on how many purge requests can be done within 24 hours. The 24 hours starts from the moment you Purge. So if you have 2 Purge requests available and Purge twice within an hour, then you can Purge again in 23 hours (for the first Purge request) and then again in 24 hours (for the second Purge request).

In the Purge Cache section, you can see how many Purge requests you have available and when.

Plan specific features

Access to the different options varies depending on the Umbraco Cloud Plan your project is on. Currently, the features available are as follows:

• Starter:

  • Enable Cache

  • Cache TTL (see below for minimum TTL)

• Standard:

  • Enable Cache

  • Cache TTL (see below for minimum TTL)

  • Cache Everything

• Professional:

  • Enable Cache

  • Cache TTL (see below for minimum TTL)

  • Cache Everything

The minimum Cache TTL varies as follows:

• Starter: 2 hours/120 minutes

• Standard: 30 minutes

• Professional: 2 minutes

The number of Cache Purge requests within 24 hours:

• Starter: 2

• Standard: 10

• Professional: 20

CDN Caching and Optimizations

From your Umbraco Cloud Project, click CDN Caching & Optimization from the Settings dropdown to configure the caching options. All settings are scoped per environment, so if you have multiple environments and add your hostnames to different environments you can select the environment at the top of the page.

Aside from environments, the CDN Caching & Optimization page is divided into two parts: Default Settings and Hostname Specific Settings.

Use the Default settings to configure default settings that should be applied to new and existing hostnames.

If you want to have different caching options for different hostnames, then select the hostname under Hostname-specific settings and adjust the options for that specific hostname. This might be useful if you want to test the different options on another hostname than your primary hostname.

Public Access lets you deny access to your Umbraco Cloud project.

When enabled only team members on the project and users whose IPs have been allowed, can access the frontend of the project.

All environments on Umbraco Cloud projects can be protected by Public access. It requires you to enter your Cloud credentials in order to view the frontend.

How to enable Basic Authentication and allow IPs

1. Go to Public Access in the project settings tab

2. Enable Basic Authentication on the project

1. Once enabled Add IPs for users that need access to the project

Once Basic Authentication has been enabled, users not on the project or with IPs not added to the allowlist will be prompted to log in.

The following changes in Certificate Authority (CA) used to issue certificates for all Umbraco Cloud sites' for new and existing custom hostnames.

Certificates for new custom hostnames

From September 26, 2022, certificates are issued using 'Google Trust Services' instead of 'DigiCert', and Certificate validity will be decreased from 1 year to 90 days.

Certificates for existing custom hostnames

From October 31, 2022, certificate renewals will no longer use 'DigiCert' as the issuing CA. The renewed certificate will instead be issued by 'Google Trust Services', and certificate validity will be decreased from 1 year to 90 days.

No action is required unless you set a Certificate Authority Authorization (CAA) record on your domain.

From October 31, 2022, Certificate renewals will no longer use 'DigiCert' as the issuing CA. This means that you need to update your CAA record to allow 'Google Trust Services' issuing certificates for your domain.

The CAA record should be changed from:

to

In this article, you can read about how you can upgrade your Umbraco Cloud plan and what you need to be aware of before you do so.

Before you upgrade your plan

Before you decide to upgrade your Umbraco Cloud plan, you need to consider a few things:

• Changing a plan for a project will change the outgoing IP of the project. If your solution has an external service that requires whitelisting the outgoing IP of the project, please visit the documentation for prior to the upgrade.

• If you are on the Starter plan, you can either upgrade your plan to a Standard or a Professional plan.

• On the Standard plan, you have the option to upgrade to a professional plan.

• Before upgrading, make sure to check the and the features you get on the new plan.

How to upgrade your plan

The first step to upgrading your Umbraco Cloud plan is to access your project in the project overview at .

• In the project overview, you can find all the projects that you have been invited to or have created.

• From here you need to find the project that you want to upgrade the plan.

Under the project on the right side, you have a dropdown menu called settings:

In the menu, you can find a tab called "Upgrade plan".

• Clicking on the tab will direct you to the overview of the plans that you can upgrade to.

• From here you can see the different plans, the price per month, and the limitations between each of the plans.

• If you are on a Starter plan you can upgrade to the Standard and the Professional plan.

• If you are on the Standard plan you can upgrade to the Professional plan.

Follow the below steps to upgrade your plan:

1. Click on the Select Plan button to choose the plan you want to upgrade to.

2. [Optional] Choose to upgrade to a dedicated option in the next step.
3. Review the Summary to make sure that everything selected is correct in the last step.

Once you click the Upgrade Project button, the project will be upgraded to the new plan and if selected to a dedicated server.

Automatic plan upgrades

If your project/website exceeds any of the usage limits, you will automatically get upgraded to a plan that fits your actual usage to ensure your website keeps running smoothly.

We will send an email to the project owner and the technical contact(s) of the project to let you know that this has happened. The upgrade to a new plan will be reflected in your next bill and will count from the day of the upgrade.

Downgrade your plan

If you’d like to downgrade, this is possible if you make sure to lower your limit to fit the desired plan.

When you’ve lowered the required data usage, reach out to Umbraco Support and they’ll be able to help downgrade your plan. When downgrading to a lower plan, this will come to effect immediately, meaning that your usage limits will be reduced and any extra features related to your previous plan will be deactivated. You will pay for the old plan until the next scheduled bill.

To make rewrite rules on Umbraco Cloud as seamless as possible, we've installed the IIS Rewrite Module on all our Umbraco Cloud servers.

You need to use config transform to add rewrite rules.

The rewrite rules should be added to the <system.webServer><rewrite> module in your project's web.config file.

<!--
<rewrite>
    <rules></rules>
</rewrite>
-->

Best practices

When you are doing rewrite rules on Umbraco Cloud there are a few important things to keep in mind:

• Always make sure that you add a condition that negates the Umbraco Backoffice - /umbraco, otherwise, you will not be able to do deployments to/from the environment

• To be able to continue working locally with your Umbraco Cloud project, you also need to add a condition that negates localhost

Hiding the default umbraco.io URL

Once you've assigned a hostname to your Live environment, you may want to "hide" the project's default URL (e.g. example.euwest01.umbraco.io) for different reasons. Perhaps for SEO or to make it clear to your users that the site can be accessed using only the primary hostname.

One approach for this is to add a new rewrite rule to the <system.webServer><rewrite><rules> section in the web.config file. For example, the following rule will redirect all requests for the project example.euwest01.umbraco.io URL to the example.com URL (using HTTPS and including the www. prefix) and respond with a permanent redirect status.

<rule name="Redirect umbraco.io to primary hostname" stopProcessing="true">
  <match url=".*" />
  <conditions>
    <add input="{HTTP_HOST}" pattern="\.umbraco\.io$" />
    <add input="{HTTP_HOST}" pattern="^(dev-|stage-)(.*)?\.umbraco\.io$" ignoreCase="true" negate="true" />
    <add input="{REQUEST_URI}" pattern="^/umbraco" ignoreCase="true" negate="true" />
    <add input="{REQUEST_URI}" pattern="^/App_Plugins" ignoreCase="true" negate="true" />
    <add input="{REQUEST_URI}" pattern="^/sb" negate="true" /> <!-- Don't redirect Smidge Bundle -->
    <add input="{HTTP_COOKIE}" pattern="^(.+; )?UMB_UCONTEXT=([^;]*)(;.+)?$" negate="true" /> <!-- Ensure preview can render -->
	<add input="{HTTP_HOST}" pattern="^localhost(:[0-9]+)?$" negate="true" />
  </conditions>
  <action type="Redirect" url="https://www.example.com/{R:0}" redirectType="Permanent" />
</rule>

Running your site on HTTPS only

Once you've applied a certificate to your site, you can make sure that anybody visiting your site will always end up on HTTPS instead of the insecure HTTP.

To accomplish this, add a rewrite rule to the live environment's web.config in the <system.webServer><rewrite><rules> section.

For example, the following rule will redirect all requests for the site http://example.com URL to the secure https://example.com URL and respond with a permanent redirect status.

<rule name="Redirect HTTP to HTTPS" stopProcessing="true">
  <match url=".*" />
  <conditions>
    <add input="{HTTPS}" pattern="^OFF$" />
    <add input="{HTTP_HOST}" negate="true" pattern="^localhost(:[0-9]+)?$" />
    <add input="{REQUEST_URI}" negate="true" pattern="^/\.well-known/acme-challenge/" />
  </conditions>
  <action type="Redirect" url="https://{HTTP_HOST}/{R:0}" redirectType="Permanent" />
</rule>

Adding a trailing slash to your URLs

It is possible to transform all of your URLs to use a trailing slash consistently for SEO.

To accomplish this, add a rewrite rule to the Live environment's web.config in the <system.webServer><rewrite><rules> section.

For example, the following rule will redirect all requests for https://example.com/page to https://example.com/page/, and respond with a permanent redirect status. This way you can ensure that you use the trailing slashes consistently on your site.

<rule name="Add trailing slash" stopProcessing="true">
  <match url="(.*[^/])$" />
  <conditions>
    <add input="{REQUEST_FILENAME}" negate="true" matchType="IsDirectory" />
    <add input="{REQUEST_FILENAME}" negate="true" matchType="IsFile" />
    <add input="{REQUEST_FILENAME}" negate="true" pattern="(.*?)\.[a-zA-Z0-9]{1,4}$" />
    <add input="{REQUEST_URI}" pattern="^/umbidlocallogin" negate="true" />
    <add input="{REQUEST_URI}" negate="true" pattern="^/umbraco" />
    <add input="{REQUEST_URI}" negate="true" pattern="^/DependencyHandler.axd" />
    <add input="{REQUEST_URI}" negate="true" pattern="^/App_Plugins/" />
    <add input="{REQUEST_URI}" negate="true" pattern="^/\.well-known/acme-challenge/" />
  </conditions>
  <action type="Redirect" url="{R:1}/" />
</rule>

Redirect from non-www to www

Another example would be to redirect from non-www to www:

<rule name="Redirect to www prefix" stopProcessing="true">
  <match url=".*" />
  <conditions>
    <add input="{HTTP_HOST}" negate="true" pattern="^www\." />
    <add input="{HTTP_HOST}" negate="true" pattern="^localhost(:[0-9]+)?$" />
    <add input="{HTTP_HOST}" negate="true" pattern="\.azurewebsites\.net$" />
    <add input="{HTTP_HOST}" negate="true" pattern="\.umbraco\.io$" />
  </conditions>
  <action type="Redirect" url="https://www.{HTTP_HOST}/{R:0}" />
</rule>

Custom Rewrite Rules for Umbraco Cloud

An example configuration to help ensure your custom rules integrate properly:

<?xml version="1.0" encoding="utf-8"?>
<configuration xmlns:xdt="http://schemas.microsoft.com/XML-Document-Transform">
  <location path="." inheritInChildApplications="false">
    <system.webServer>
      <rewrite xdt:Transform="Insert">
        <rules>
          <!-- Add your custom rules here -->
        </rules>
      </rewrite>
    </system.webServer>
  </location>
</configuration>

Troubleshooting

Sometimes, you might experience an issue where a .azurewebsites.net link will appear instead of the custom hostname. In this case, a restart will usually fix the issue, however, it is not ideal that this appears at all.

The following redirect is a way to amend the issue where the .azurewebsites.net link appears instead of the hostname. It will redirect from the .azurewebsites.net link to the hostname of the website, should this link be called instead.

<rule name="Redirects azurewebsites.net to actual domain" stopProcessing="true">
  <match url=".*" />
  <conditions>
    <add input="{HTTP_HOST}" pattern="^(.*)?.azurewebsites.net$" />
    <add input="{REQUEST_URI}" negate="true" pattern="^/umbraco" />
    <add input="{REQUEST_URI}" negate="true" pattern="^/DependencyHandler.axd" />
    <add input="{REQUEST_URI}" negate="true" pattern="^/App_Plugins" />
    <add input="{REQUEST_URI}" negate="true" pattern="localhost" />
  </conditions>
  <action type="Redirect" url="https://www.hostname.com/{R:0}" appendQueryString="true" redirectType="Permanent" />
</rule>

Once you have added your custom hostnames to your Umbraco Cloud project, it's possible to configure certain transport security options for all or specific custom hostnames within your project. These security options all relate to the traffic that goes through your hostname from the origin (Umbraco Cloud) to the end-user - meaning the protocols and encryption used to transport your website and assets from the webserver to the browser.

Currently, these options are available:

• HTTP/2 (default: on)

• TLS 1.3 (default: off)

• Minimum TLS Version (default: 1.2)

• Web Application Firewall (WAF) (default: on)

When a new custom hostname is added to a Project it will have the default settings applied. But you can change the defaults for your Project, so new custom hostnames will get the default settings you have chosen.

HTTP/2 Explained

The first usable version of HTTP was created in 1997. Because it went through different stages of development, this first version of HTTP was called HTTP/1.1. This version is still in use on the web. In 2015, a new version of HTTP called HTTP/2 was created. HTTP/2 progressively enhances your website’s performance. When a browser supports HTTP/2, Umbraco Cloud will take full advantage of HTTP/2 performance benefits end to end. For older browsers or non-HTTPS requests, the traffic will fall back to HTTP/1.1. You don’t need to choose between better performance and backward compatibility, which is why HTTP/2 is enabled by default for all new custom hostnames added to a Umbraco Cloud project.

TLS 1.3 Explained

Transport Layer Security (TLS) TLS 1.3 is the newest, fastest, and most secure version of the TLS protocol. SSL/TLS is the protocol that encrypts communication between users and your website. When web traffic is encrypted with TLS, users will see the green padlock in their browser window. By turning on the TLS 1.3 option, traffic to and from your website will be served over the TLS 1.3 protocol when supported by clients. TLS 1.3 protocol has improved latency over older versions, has several new features, and is currently supported in both Chrome (starting with release 66), Firefox (starting with release 60), and in development for Safari and Edge browsers.

Minimum TLS Version Explained

The minimum TLS Version only allows HTTPS connections from visitors that support the selected TLS protocol version or newer. This option relates to the TLS versions mentioned above and the current default, which is TLS 1.2. If you want your website traffic to only use TLS 1.3 you can change the minimum version. But be mindful of the implications that this might have (see browser support above). You don't need to change the minimum version to use TLS 1.3.

WAF Explained

A Web Application Firewall (WAF) is a security solution designed to protect web applications by filtering and monitoring HTTP traffic between them and the Internet. Common attacks like cross-site scripting, SQL injection, and file inclusion are mitigated by acting as a shield between the web application and potential threats. For more detailed information, please refer to our WAF section.

Plan specific features

Access to the different options varies depending on the Umbraco Cloud plan your project is on. Currently, the features are available as follows:

• Starter: HTTP/2

• Standard: HTTP/2, TLS 1.3, Minimum TLS Version

• Professional: HTTP/2, TLS 1.3, Minimum TLS Version

Security subpage

Click Security from the Settings dropdown on your Umbraco Cloud Project. The Security settings are scoped per environment, so if you have multiple environments and add your custom hostnames to different environments you can select the environment at the top of the page.

Aside from the environments, the Security page is divided into 'Default Settings' and 'Hostname Specific Settings'. Use the Default Settings to configure what should be applied to new and existing custom hostnames by default.

If you want to have different security options for different custom hostnames, then select the custom hostname under Hostname Specific Settings and adjust the options for that specific hostname. This might be useful if you want to test the different options on another custom hostname than your primary hostname.

Cipher Suite Management

On the security page, it's possible to enable or disable the different cipher suites for your project.

Enabling or disabling the different ciphers can be done under the minimum TLS version in the Ciphers drop-down:

Like the other Hostname Specific Settings, you can enable/disable specific ciphers for your custom hostname based on your needs.

Umbraco CI/CD Flow is designed to facilitate the seamless integration of your existing CI/CD flow with Umbraco Cloud. The primary objective of this feature is to enable your automated workflows to deploy directly to Umbraco Cloud. This lets you leverage the best of both worlds: the robustness of your current CI/CD setup and the specialized hosting environment of Umbraco Cloud.

Umbraco Cloud continues to be a cornerstone in this setup, providing a cloud-based hosting solution specifically optimized for Umbraco CMS. With integration to your Continuous Integration and Continuous Deployment (CI/CD) pipeline, Umbraco CI/CD allows the inclusion of automated workflows. These automated workflows include building, testing, and deploying your Umbraco projects.

Advantages of Utilizing Umbraco CI/CD Flow

Explore the practical benefits of using Umbraco CI/CD Flow for your development and deployment needs. This solution aims to simplify your workflow, improve team collaboration, and reduce deployment time. Here are some key advantages to consider:

Seamless Integration with Existing CI/CD

• Umbraco CI/CD Flow allows customers to connect their existing CI/CD pipelines to Umbraco Cloud, making the transition smoother and reducing the learning curve.

Enhanced CI/CD Features

• The feature enables unique CI/CD features like PR-flows and automated tests, which are not natively available in Umbraco Cloud. This adds a layer of quality assurance and streamlines the development workflow.

Scalability and Flexibility

• Umbraco CI/CD Flow allows for greater scalability and flexibility in your deployment process. You can adapt your existing CI/CD pipeline to handle larger projects or more complex workflows without having to overhaul your Umbraco Cloud setup.

Centralized Management

• With Umbraco CI/CD Flow, you can centralize the management of your deployments, tests, and workflows. This makes it easier to monitor, troubleshoot, and optimize your processes, leading to more efficient and reliable deployments. Automating deployment minimizes the risc for human errors that could have a negative effect on the target environment.

Umbraco CI/CD Flow serves as a bridge between your existing CI/CD pipeline and Umbraco Cloud, enabling a more streamlined and automated deployment process. While it offers a number of advantages, there are also limitations that need to be considered. On the page 'Known Limitations and Considerations' you will find a detailed list of the pros and cons of using Umbraco CI/CD Flow.

Overview of Flow

The CI/CD process for Umbraco projects involves some key steps, from code development locally to deployment to Umbraco Cloud. The flow is generally as follows:

1. Code Development: Developers work on features or bug fixes in their local environments.

2. Customer code repository: Changes are committed and pushed to a version control system like Git in the customer's own repository.

3. Customer pipeline: The code is compiled and built. Tests can be run automatically in the associated pipeline to ensure code quality. Finally, the code is packaged into a zip file and prepared for deployment.

4. Umbraco Cloud API: The customer pipeline uploads the source packed as a zip file to Umbraco Cloud API.

5. Umbraco cloud repository: The deployments start which triggers the queueing of the build in Umbraco services. It then pushed the Umbraco Cloud repository to the left-most environment. And if a live environment, the website has been updated.

In a bit more detail the flow will look like this from a pipeline perspective.

Next Steps: Dive into the Documentation

To ensure you make the most of Umbraco CI/CD Flow, we suggest exploring the documentation further. Familiarizing yourself with the fundamentals is a good starting point, but delving deeper will enable you to fully harness its capabilities.

Here are three essential pages to get you started:

1. How to use the Umbraco Cloud API for CI/CD Flow: Gain a comprehensive understanding of how to interact with the Umbraco Cloud API for seamless deployments and management.

2. How To Configure A Sample CI/CD Pipeline: Follow our step-by-step guide to set up a sample pipeline, making your development and deployment process more efficient.

3. Known Limitations and Considerations: Familiarize yourself with the current limitations and considerations to ensure you're making the most out of Umbraco CI/CD Flow.

These resources will provide you with the knowledge and tools you need to successfully implement and optimize your use of Umbraco CI/CD Flow.

Before setting up the pipeline in Azure DevOps, make sure that the following steps from the Configuring a CI/CD pipeline are done:

• Pick a Cloud project

• Activate CI/CD Flow

Next, you will need to define your pipeline in YAML and use it to interact with the Umbraco Cloud API.

Import Cloud project repository to Azure DevOps

Go to your repositories in Azure DevOps and click on "Create a repository".

• Create a new empty repository (don't add a README and don't add a .gitignore), and note down the clone URL.

• Go to the Umbraco Cloud Portal and clone your cloud project down locally. This article describes how you can find the clone URL.

• Now working locally remove the Git Remote called origin, which currently points to Umbraco Cloud

git remote remove origin

• Optionally rename branch master to main

# optional step
git branch -m  main
git symbolic-ref HEAD refs/heads/main

• Add a new remote called origin and pointing to the Azure DevOps clone URL and push

git remote add origin https://{your-organization}@dev.azure.com/{your-organization}/{azure-project-scope}/_git/{your-repository}
git push -u origin --all

Now we can move on to setting up a pipeline.

Set up the Azure DevOps pipeline files

While working with the project on your local machine, follow these steps to prepare the pipeline, using the samples from the repository.

Select your preferred scripting language:

Configure Azure DevOps

The pipeline needs to know which Umbraco Cloud project to deploy to. In order to do this you will need the Project ID and the API Key. This article describes how to get those values.

• Now go to the repository in Azure and click on "Set up build".

• On the next screen click on "Existing Azure Pipelines YAML file"

• Select main (or master if you did not change the branch name) in Branch

• Select /devops/azure-release-pipeline.yaml in Path and continue

• Now you are on the "Review your pipeline YAML" screen

  • Replace the ##Your project Id here## with the Project Id you got from Umbraco Cloud Portal

  • Click on "Variables"

• Add the variable umbracoCloudApiKey with the value of the API Key you got from Umbraco Cloud Portal

When you click on "Save and Run" your first deployment will be triggered. Which means that Azure DevOps is set up with all the needed information to be able to deploy your Cloud project back to Umbraco Cloud.

Optional: Test the pipeline

With everything set up, you may want to confirm that Umbraco Cloud reflects the changes you are sending via your pipeline.

While working on your project locally, add a new Document type.

• Commit the change to main branch (or master if you did not change the branch name) and push to your repository.

• The pipeline starts to run

• Once the pipeline is done log into Backoffice on your left-most environment in Umbraco Cloud

• Go to the Settings section and see that your new Document type has been deployed

High level overview of the pipeline components

The mentioned scripts are provided as a starting point. It is recommended that you familiarize yourself with the scripts and with documentation related to how to use Azure DevOps.

The scripts demonstrates the following:

• How to sync your Azure DevOps repository with the left-most project environment in Umbraco Cloud

• How to deploy changes to the left-most project environment in Umbraco Cloud

Main

The azure-release-pipeline.yaml is the main pipeline, and is the one that will be triggered on a push to main branch. You can configure a different trigger behavior in this file.

You can add your Build and Test stage between the cloudSyncStage and cloudDeploymentStage stages. Keep in mind that you do not need to retain the dotnet build artifact for upload later. The cloudDeploymentStage job will take care of packaging all your source code and upload to Umbraco Cloud.

Cloud-sync

The cloud-sync.yml shows how you can sync your Azure DevOps repository with the left-most environment of your Cloud project. In this sample, it accepts any change from the API and applies and commits it back to the branch which triggered the pipeline. However the commit does not trigger the pipeline again.

If you don't want the pipeline to commit back to the triggering branch, this is where you need to change the pipeline.

Cloud-deployment

The cloud-deployment.yml shows how you can deploy your repository to the left-most environment of your Cloud project. The sample shows how to prepare for deployment, request the deployment and wait for cloud to finish.

There are a couple of things here to be aware of:

• We are overwriting the .gitignore file with cloud.gitignore. This is a way to accommodate your gitignore-needs when working locally. For instance you might want to ignore frontend builds, but you want them build and published to cloud.

• We have a special cloud.zipignore file. This is a convenient way to tell the pipeline which files not to include when creating the zip package to send to cloud.

Further information

• Azure Pipelines Documentation

Learn how to configure a CI/CD pipeline in Azure DevOps and GitHub Actions Workflows using the sample scripts provided.

You'll find example shell scripts and pipeline configurations in the Sample scripts section, covering both Azure DevOps and GitHub Actions Workflows.

Why should one configure a sample CI/CD pipeline?

Umbraco Cloud repositories are not meant to be used as source code repositories. More details here.

Once you commit your code to Cloud the build pipeline converts your C# code to DLLs and deploys it on the respective environment.

You can use Azure DevOps as an external repository and with the pipelines, it will automatically keep your Azure DevOps source code repository in sync. The sync is done with the git repository of Umbraco Cloud of the development environment.

Setting Up an Umbraco Cloud Project

Before proceeding, you'll need an Umbraco Cloud project and a CI/CD pipeline. You will also need the required files to add to your pipeline for successful interaction with the Umbraco Cloud API.

1. Pick an Umbraco Cloud project, preferably with a development environment (but not a requirement)

• Create a new Umbraco Cloud Project.

  • You can take a trial here

  • Create a new project in the Umbraco Cloud Portal

• Use one of your existing projects.

1. Create a new or an existing CI/CD pipeline in Azure DevOps or GitHub Actions.

Obtaining the Project ID and API Key

To get started with API interactions, you'll need to obtain your Project ID and API key. If you haven't already enabled the CI/CD feature, follow these steps:

1. Navigate to the Umbraco Cloud Portal and select your project.

2. Go to Settings -> Advanced. This is where you can generate an API key and find your Project ID.

1. Click on "Activate CI/CD Flow" toggle to enable the feature.

Sample pipelines

Below we have a couple of examples of how to set up a CI/CD Pipeline using either Azure DevOps or GitHub Actions.

Each guide describes:

• How to set up a new repository in either GitHub or Azure DevOps

• Get a copy of your Umbraco Cloud project into that repository

• And finally how to configure a new pipeline using the provided samples

The sample pipelines are using either Bash-scripts or Powershell-scripts to facilitate communication with the Umbraco CI/CD API.

Azure DevOps sample

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

• Azure DevOps Sample

GitHub Actions sample

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

• GitHub Actions Sample

The Umbraco Cloud API serves as a publicly accessible endpoint that customers can utilize to execute relevant tasks.

While its initial focus is on automating and managing deployments in Umbraco Cloud projects via the "Umbraco CI/CD Flow," future enhancements will broaden its capabilities to encompass a wider range of activities and options for Umbraco Cloud users.

For the scope of this discussion, we will concentrate solely on the endpoints associated with interactions within the Umbraco CI/CD Flow.

Getting started

To integrate Umbraco Cloud into your CI/CD pipeline, you'll need to make API calls to the following endpoint https://api.cloud.umbraco.com:

• /$projectId/deployments

• /$projectId/deployments/$deploymentId

• /$projectId/deployments/$deploymentId/package

• /$projectId/deployments/$latestCompletedDeploymentId/diff

You will find relevant examples using Curl and Powershell in the sections below.

How to enable CI/CD Integrator in the Umbraco Cloud Portal

To authenticate with the Umbraco Cloud API, you'll need your Project ID and API Key. These credentials can be found under Configuration > Advanced in the Umbraco Cloud portal.

The two elements to be used for the authentication are:

• Cloud Project ID: The ID of your Umbraco project.

• CI/CD API Key: Your unique identifier.

By including the API key header in your HTTP requests, you ensure secure access to your Umbraco Cloud project's resources.

For enhanced security, it's crucial to store the provided API key in a secure location. Options include a variable group in Azure DevOps or using the Secrets feature in GitHub Actions. It's important to note that each API key is tightly coupled with a specific Umbraco Cloud project and can only be used for deployments related to that project.

How to authenticate your requests

To authenticate your requests, include the API key in a custom HTTP header named API key.

PowerShell is a command-line shell and scripting language commonly used for automating tasks and managing configurations. It offers a versatile set of cmdlets that allow you to interact with APIs, manipulate files, and much more. Within the context of the Umbraco Cloud API, PowerShell can be employed to authenticate your requests by incorporating your unique API key.

Curl (Client URL) is a command-line tool commonly used for making HTTP requests. It's a versatile utility that allows you to interact with APIs, download files, and more. In the context of Umbraco Cloud API, curl can be used to authenticate your requests by including your unique API key.

To authenticate your API requests using curl, you'll need to include your API key in a custom HTTP header named Umbraco-Cloud-Api-Key. Here's how typical Powershell and curl commands would look for this purpose:

Invoke-RestMethod -Uri $url -Headers @{ "Umbraco-Cloud-Api-Key" = $apiKey } -Method Get

curl -s -X GET $url -H "Umbraco-Cloud-Api-Key: $apiKey"

How to make a deployment to Umbraco Cloud using the Umbraco CI/CD API

Create the deployment

The Create Deployment endpoint initiates a new deployment and returns a unique deploymentId. This call serves as the initial step in the deployment process. It requires a projectId specified in the URL path and a commit message included in the request body. Essentially, this establishes the metadata necessary for initiating the deployment process. If a deployment is already underway, initiating a new one will be possible but should be avoided.

To create a deployment, you'll need to make an HTTP POST request. The request body should contain a simple JSON object with the commit message:

{
    "commitMessage": "New dashboard for customer sales numbers"
}

In Powershell, the command to initiate a new deployment would be as follows

...
$url = "https://api.cloud.umbraco.com/v1/projects/$projectId/deployments"
$headers = @{
    "Umbraco-Cloud-Api-Key" = $apiKey
    "Content-Type" = "application/json"
}

$body = @{
    commitMessage = $commitMessage
} | ConvertTo-Json

Invoke-RestMethod -Uri $url -Headers $headers -Method Post -Body $body

In curl, the command to initiate a new deployment would be as follows

...
url="https://api.cloud.umbraco.com/v1/projects/$projectId/deployments"

curl -s -X POST $url \
    -H "Umbraco-Cloud-Api-Key: $apiKey" \
    -H "Content-Type: application/json" \
    -d "{\"commitMessage\":\"$commitMessage\"}"

Part of the returned response will be the actual deploymentId. The response from the API should be an HTTP 201 Created response including a deploymentId. This ID can be stored in the pipeline variables so it can be used in later steps.

{
    "deploymentId": "bc0ebd6f-cef8-4e92-8887-ceb862a83bf0",
    "projectId" : "abcdef12-cef8-4e92-8887-ceb123456789",
    "projectAlias": "",
    "deploymentState": "Created",
    "updateMessage": "",
    "errorMessage": "",
    "created": "2023-05-02T07:16:46.4183912",
    "lastModified": "2023-05-02T07:16:48.8544387",
    "completed": null
}

Upload zip source file

To deploy content to the Umbraco Cloud repository, you need to perform an HTTP POST request to the Umbraco Cloud API. The deployment content should be packaged as a ZIP file, which must mirror the expected structure of the Umbraco Cloud repository. This ZIP file should include all relevant files such as project and solution files, and compiled frontend code. If your setup includes a frontend project with custom elements, the build artifacts from that project should also be included in the ZIP file, and placed in the appropriate directory within the repository structure.

The HTTP POST request should be made using the multipart/form-data content type. The request URL should incorporate both the projectId and deploymentId obtained from the previous step in the API path.

The ZIP file must be structured the same way as described in the Readme.md included in all cloud projects starting from Umbraco 9. This also means if you need to change the name and/or structure of the project, you should follow the guide in the same Readme.

By adhering to these guidelines, you ensure that the uploaded content is an exact match with what is expected in the Umbraco Cloud repository, facilitating a seamless deployment process.

The purpose of packaging your content into a ZIP file is to replace the existing content in the Umbraco Cloud repository upon unpackaging. This ensures that the repository is updated with the latest version of your project files.

Make sure your ZIP archive does not contain .git folder. If you're using the .zipignore file, you can add the following line .git/* to exclude it.

A note about .gitignore

Umbraco Cloud environments are using git internally. This means you should be careful about the .gitignore file you add to the package. If you have “git ignored” build js assets locally, you need to handle this so that this is not being ignored in the cloud repository.

Note: If the .gitignore file within the ZIP package does not exclude bin/ and obj/ directories, these will also be committed to the Umbraco Cloud repository.

Best Practice: If you have frontend assets your local repository's .gitignore file will most likely differ from the one intended for the Umbraco Cloud repository, it's advisable to create a separate .cloud_gitignore file. Include this file in the ZIP package and rename it to .gitignore before packaging. This ensures that only the necessary files and directories are uploaded and finally committed to the Umbraco Cloud repository.

In curl uploading the source file will be:

...
url="https://api.cloud.umbraco.com/v1/projects/$projectId/deployments/$deploymentId/package"

curl -s -X POST $url \
    -H "Umbraco-Cloud-Api-Key: $apiKey" \
    -H "Content-Type: multipart/form-data" \
    --form "file=@$file"

The response of this call will be the same deployment object (in JSON) as when creating a new deployment, but the deploymentState should now be 'Pending':

{
    "deploymentId": "bc0ebd6f-cef8-4e92-8887-ceb862a83bf0",
    "projectId" : "abcdef12-cef8-4e92-8887-ceb123456789",
    "projectAlias": "cicd-demo-site",
    "deploymentState": "Pending",
    "updateMessage":"Project information set\nDeployment pending\nDownloadUri set",
    "errorMessage": "",
    "created": "2023-05-02T07:16:46.4183912",
    "lastModified": "2023-05-02T07:17:48.8544387",
    "completed": null
}

Start Deployment

After the source file has been uploaded the deployment can be started. This will queue the deployment in the Umbraco Cloud services which will start the deployment as soon as possible. Starting the deployment is an HTTP PATCH request to the Umbraco Cloud API. projectId and the deploymentId from the previous step must be included in the path, and the deployment state set to 'Queued' in the request body.

In curl starting a deployment will be:

...
url="https://api.cloud.umbraco.com/v1/projects/$projectId/deployments/$deploymentId"

curl -s -X PATCH $url \
    -H "Umbraco-Cloud-Api-Key: $apiKey" \
    -H "Content-Type: application/json" \
    -d "{\"deploymentState\": \"Queued\"}"

The response of this call will be the same deployment object (in JSON) as when creating a new deployment, but the deploymentState should now be 'Queued':

{
    "deploymentId": "bc0ebd6f-cef8-4e92-8887-ceb862a83bf0",
    "projectId" : "abcdef12-cef8-4e92-8887-ceb123456789",
    "projectAlias": "cicd-demo-site",
    "deploymentState": "Queued",
    "updateMessage": "Project information set\nDeployment pending\nDownloadUri set\nDeployment queued",
    "errorMessage": "",
    "created": "2023-05-02T07:16:46.4183912",
    "lastModified": "2023-05-02T07:18:48.8544387",
    "completed": null
}

Get Deployment status

To monitor the status of a deployment—whether it's completed, successful, or otherwise — you can periodically query the 'Get Deployment Status' API. This API endpoint is an HTTP GET request to the Umbraco Cloud API, and it requires both the projectId and the deploymentId obtained from previous steps to be included in the path.

Deployments in Umbraco services can take varying amounts of time to complete. Therefore, it's advisable to poll this API at regular intervals to stay updated on the deployment's current state. For example, in a simple project, you might choose to poll the API every 15 seconds for a duration of 15 minutes. These figures are just a starting point; the optimal polling frequency and duration may differ for your specific pipeline. Based on initial experience, a 15-minute window generally suffices, but we welcome your feedback to fine-tune these parameters.

Using a curl command, polling for the deployment status would look like this:

...
url="https://api.cloud.umbraco.com/v1/projects/$projectId/deployments/$deploymentId"

# Define a function to call API and check the status
function call_api {
  response=$(curl -s -X GET $url \
    -H "Umbraco-Cloud-Api-Key: $apiKey" \
    -H "Content-Type: application/json")
  echo "$response"
  status=$(echo $response | jq -r '.deploymentState')
}

# Call API and check status
call_api
while [[ $status == "Pending" || $status == "InProgress" || $status == "Queued" ]]; do
  echo "Status is $status, waiting 15 seconds..."
  sleep 15
  call_api
  if [[ $SECONDS -gt 900 ]]; then
    echo "Timeout reached, exiting loop."
    break
  fi
done

# Check final status
if [[ $status == "Completed" ]]; then
  echo "Deployment completed successfully."
elif [[ $status == "Failed" ]]; then
  echo "Deployment failed."
  exit 1
else
  echo "Unexpected status: $status"
  exit 1
fi

The response from this API call will return the same deployment object in JSON format as you would receive from other API interactions. Ultimately, the deploymentState field will indicate either 'Completed' or 'Failed'. Should the deployment fail, the 'ErrorMessage' field will provide additional details regarding the issue.

{
    "deploymentId": "bc0ebd6f-cef8-4e92-8887-ceb862a83bf0",
    "projectId" : "abcdef12-cef8-4e92-8887-ceb123456789",
    "projectAlias": "cicd-demo-site",
    "deploymentState": "Completed",
    "updateMessage":"Project information set\nDeployment pending\nDownloadUri set\nDeployment queued\nDeployment triggered\nDeployment started\nCheck blocking markers\nCreate updating marker\nGit Clone\nDownload update\nExtract Update\nChecking versions\nDeleting repository files\nCopying files to repository\nNuGet Restore\nDotnet Build\nGit Stage\nGit Commit\nGit Tag\nGit Push\nDelete updating marker\nDeployment successful",
    "errorMessage": "",
    "created": "2023-05-02T07:16:46.4183912",
    "lastModified": "2023-05-02T07:20:48.8544387",
    "completed": "2023-05-02T07:20:49.8544387"
}

Get Deployments

The endpoint lets you retrieve a list of completed deployments. It can only list deployments that has been run through the api.

The API allows you to filter and limit the number of returned deployments using query parameters:

• Skip : optional, zero or positive integer

• Take : optional, zero or positive integer

• Includenulldeployments : optional, boolean, defaults to true

The "skip" and "take" parameters, while optional, are always required to be used together.

With includenulldeployments set to true, you will get all completed deployments, including those that did not create any new changes in the cloud repository.

To fetch the list of deployments using a curl command, the syntax would be as follows:

...
url="https://api.cloud.umbraco.com/v1/projects/$projectId/deployments?skip=0&take=1&includenulldeployments=false"

response=$(curl -s -X GET $url \
    -H "Umbraco-Cloud-Api-Key: $apiKey" \
    -H "Content-Type: application/json")
latestDeploymentId=$(echo $response | jq -r '.deployments[0].deploymentId')

The response from this API call will return an object containing a list of deployment objects. The deployment-objects are consistent with the structure used in other API responses. Deployments are listed in descending order based on their creation timestamp.

{
  "projectId": "abcdef12-cef8-4e92-8887-ceb123456789",
  "deployments":
    [
      {
        "deploymentId": "bc0ebd6f-cef8-4e92-8887-ceb862a83bf0",
        "projectId" : "abcdef12-cef8-4e92-8887-ceb123456789",
        "projectAlias": "cicd-demo-site",
        "deploymentState": "Completed",
        "updateMessage": "...",
        "errorMessage": "",
        "created": "2023-05-02T07:16:46.4183912",
        "lastModified": "2023-05-02T07:18:48.8544387",
        "completed": "2023-05-02T07:22:48.8544387"
      }
    ]
}

Get Deployment diff

Sometimes updates are done directly on the Umbraco Cloud repository. We encourage you to not do any actual work there, but auto-upgrades and environment changes will affect the umbraco-cloud-git-repos. To keep track of such changes, you can use the 'Get Deployment Diff' API. This API endpoint will provide you with a git-patch file detailing the changes between a specific deployment and the current state of the repository. To make this API call, you'll need to include both the projectId and the deploymentId of the deployment you want to check for differences against. This is a standard HTTP GET request.

Using a curl command, fetching the potential differences would look like this:

url="https://api.cloud.umbraco.com/v1/projects/$projectId/deployments/$latestCompletedDeploymentId/diff"
downloadFolder="tmp"
mkdir -p $downloadFolder # ensure folder exists

responseCode=$(curl -s -w "%{http_code}" -L -o "$downloadFolder/git-patch.diff" -X GET $url \
    -H "Umbraco-Cloud-Api-Key: $apiKey" \
    -H "Content-Type: application/json")

if [[ 10#$responseCode -eq 204 ]]; then # Http 204 No Content means that there are no changes
  echo "No changes"
  rm -fr $downloadFolder/git-patch.diff
elif [[ 10#$responseCode -eq 200 ]]; then # Http 200 downloads the file and set a few variables for pipeline
  echo "Changes - check file - $downloadFolder/git-patch.diff"
else
  echo "Unexpected status: $responseCode"
  exit 1
fi

The API response will vary based on whether or not there are changes to report. If no changes are detected, you'll receive an HTTP 204 No Content status. On the other hand, if there are changes, the API will return an HTTP 200 OK status along with a git-patch file as the content. This git-patch file can then be applied to your local repository to sync it with the changes.

Promote Deployment

Currently, the feature to transition from a development environment to staging or live, and from staging to live, is pending implementation. In the meantime, you can manage these transitions manually through the Umbraco Cloud Portal [link to relevant page in docs.umbraco.com, e.g. the section “Utilizing the Pipeline” of the new page “How To Configure A Sample CI|CD Pipeline”]..

Possible errors

When interacting with the Umbraco Cloud API, you may encounter various HTTP status codes that indicate the success or failure of your API request. Below is a table summarizing the possible status codes, their corresponding errors, and basic root causes to guide your troubleshooting:

Most errors have a response body that corresponds to this JSON, and the “detail” field will have a more complete error message.

{
  “title”: string,
  “status”: number,
  “detail”: string,
}

As we continue to gather insights from our users, there are some known limitations and considerations to be aware of.

Potential Limitations and Considerations

Format Restrictions

• The packaged artifact from your CI/CD pipeline must adhere to the Umbraco Cloud API's required format, which is a zip source file. This could necessitate changes to your existing build and packaging scripts.

Workflow considerations

• To ensure smooth execution of the CI/CD Flow, it is recommended to make schema changes in the . Ideally, this means the local development environment. Schema changes include changes made to Document Types, Data Types, Templates, and the like. The intention behind this principle is to prevent conflicts that could potentially arise due to simultaneous modifications made in different environments.

Additional Build Step

• The flow feature adds an extra build to the deployment process. As a result, it takes longer to post to Umbraco Cloud using Umbraco CI/CD Flow compared to standard deployments.

Conflict Management

• Given the necessity to avoid changes in other environments, the lack of strict coordination among multiple teams or individuals working on the same project elevates the risk of conflicts.

Key Points to Consider

• Direct Commits to Umbraco Git Repos: Any commits made directly to the Umbraco-git-repos will cause the process to fail.

• Remote Build/Test Options: It is currently not possible to skip the first build step before committing.

• Incomplete API:

  • The list endpoint lacks filtering capabilities.

  • The promotion endpoint for transitioning from dev to stage to live is not fully functional yet.

• Hotfix Deployments: Direct deployments to a specific environment are not supported at this time.

• Lack of Predefined Tasks: There are no Umbraco-provided Azure DevOps tasks or GitHub Actions available.

• No Webhooks: Currently, there's no webhook support for real-time feedback to the pipeline; polling is the only option.

• Casing Conflicts: Be cautious of casing issues, such as having a README.md file created by Azure DevOps and a Readme.md file from the default Umbraco Cloud, as this can cause conflicts in the cloud Git repository.

• Documentation Alignment: We are in the process of updating our documentation to align with standard Umbraco guidelines.

• Developer Experience: Plans are underway to create Umbraco-specific Azure DevOps tasks and GitHub Actions to enhance the developer experience.

In some cases, Umbraco Cloud might not be the only service you are working with. You might need to work with other services as well - this could be either internal or third-party services. In either case, it will be serviced externally to Umbraco Cloud.

When you are working with an external service that is behind a firewall and that service needs to communicate with your Umbraco Cloud project, you need to make sure the Umbraco Cloud Server IPs are allowed to bypass the firewall.

An example could be, that you're fetching some information from an external service that is behind a firewall. To give your Umbraco Cloud project access to the external service you need to add the IPs used by the Umbraco Cloud servers to an allow list (other services may refer to it as a "whitelist").

Enabling static outbound IP addresses

For projects on a Standard, Professional, and Enterprise plan you can enable static outbound IP addresses.

On the Advanced page of your project, you can turn on the static outbound IP address feature to ensure persistent communication. This opt-in feature can be switched on for Standard, Professional, and Enterprise Cloud projects.

West Europe

UK South

US East

Australia East

If you need to use a CIDR (Classless Inter-Domain Routing) Range for the IPs: 40.113.173.32/28

Special Cases

Using RestorePackagesWithLockFile in your .csproj file

If RestorePackagesWithLockFile is used and set to true, you will experience that no changes will be made to the website. This happened even though the CI/CD deployments were completed successfully, and files were updated as expected in the Cloud repository.

The reason for this is that the KUDU deploy process fails. This process takes the newly committed files from the cloud repository and runs restore, build, and publish on the cloud environment.

To resolve this issue, remove the RestorePackagesWithLockFile to allow the deployments to go through as expected.

cloud-sync

The projects left-most environment has changed

The mechanism to determine changes since the last deployment is not able to do so when the left-most environment has changed. This happens when you either add or remove the development environment. The responds with status 409 and the following json payload:

You will need to manually make sure that all latest changes on your left-most environment in cloud is also present in your local copy.

Once this is done you can run a new deployment, where you skip the cloud-sync step.

“Apply Remote Changes” step is failing

The sample pipelines are naively trying to apply any change coming from the generated patch file on cloud. This doesn't always work and you might see an error similar to the following:

The root cause is due to conflicts between your source and the code in the repository on Umbraco Cloud. This is usually due to one of two things:

1. Cloud project package(s) has been auto-upgraded, and that diff was already applied.

In both cases you have to make sure that your repository is up too speed with any changes there are in the cloud environment. You will have to resolve potential conflicts manually.

Once that has been done, you should run a new deployment without the cloud-sync step.

Skip cloud-sync in GitHub

1. Ensure your GitHub repository is up-to-date with any changes in your Umbraco Cloud environment.

2. Locate the main.yml file in the following directory: {projectname}.github\workflows on tour local project.

3. Open the main.yml file in a text editor and navigate to the “jobs” section.

4. Comment out the entire “cloud-sync” section and the “needs: cloud-sync” under “cloud-deployment”. An example is provided in the screenshot below.

1. Commit the changes, and push them to GitHub. This action will trigger a build and run the pipeline.

2. At this point, the pipeline should execute successfully and your changes will be pushed to Umbraco Cloud. If this is the case, proceed to the next step.

3. Uncomment the lines you previously commented out and make a new commit. Push these changes to GitHub.

• Optional: Add "[skip ci]" to the last commit message, to avoid automatically triggering the pipeline

Your pipeline should now be functioning as expected.

Skip cloud-sync in Azure DevOps

With a few clicks you can manually trigger a pipeline to run without the cloud-sync:

1. Ensure that your Azure DevOps repository is up to date with any changes in your Umbraco Cloud environment.

2. Find the pipeline in Azure DevOps.

3. Click on "Run Pipeline" in the top right corner.

1. Click on "Stages to run"

1. Uncheck the "Umbraco Cloud Sync" checkbox. Confirm on "Use selected stages".

1. Click on "Run" back in the "Run Pipeline" view.

As no changes were made to your pipeline, it will run as usual on next push to Azure DevOps.

Upload Errors

Failed to read the request form. Multipart body length limit 134217728 exceeded

We currently have a size limit set to 134217728 bytes or about ~128 MB.

Make sure that the package you are trying to upload does not contain anything unnecessary.

Deployment failed

Cannot apply update because the following packages would be downgraded: Package: Umbraco.{abc}, Version: {x.y.z}

The service goes through all .csproj-files contained in the uploaded package, and compares that to the versions running in your left-most cloud environment. We do this to try to prevent you from downgrading the crucial Umbraco packages used by cloud.

The full error could look like this:

The error tells you which package to look for and which version is currently in your left-most cloud environment. The error also contains the problematic incoming .csproj-file and the version referenced by it.

If the incoming package references multiple packages with lower versions, the error will list each one.

We recommend aligning the package versions in your .csproj files with the higher version mentioned in the error for that package or a later version.

If you have orphaned csproj-files you should remove them or rename them. Orphaned would be backup .csproj files or files not referenced by any of the main project files nor referenced in a .sln file.

Could not find '/app/work/repository/Readme.md' to stat: No such file or directory

In some instances we see an issue where filename casing is causing an error.

Rename the Readme.md file in the root of your repository to something different, the file can keep the markdown-extension. Commit the change to your repository and run the pipeline.

If you want you can change the filename back to Readme.md after a successful CI/CD deployment.

The site can't be upgraded as it's blocked with the following markers: updating

In rare cases deployments fail, and the cloud infrastructure doesn't clean up correctly. This leaves behind an "updating" marker. The next time you try to deploy through your pipeline you will encounter an error.

1. Access KUDU on the "left-most" environment

• If you only have one environment you want the live environment

• If you have more than one environment, you want the development environment

1. Navigate to site > locks folder In there, there should be a file named updating

2. Remove the updating file.

Once the marker file is removed, run your pipeline again.

Environment errors after deployment

Unable to determine environment by its {environment-id}

This happens when you use the CI/CD feature of Umbraco Cloud to deploy changes to your live environment, and later add a development environment. Your development environment will fail to boot up and will show the following error message:

This issue arises because the development environment is missing in the local umbraco-cloud.json file. To resolve this issue, follow these steps:

1. Navigate to Kudu in your Live environment

2. Select “Debug console” and choose “CMD”.

3. Find the umbraco-cloud.json file. Path to this file may vary depending on your setup, but the default location on cloud is C:\home\site\repository\src\UmbracoProject

4. Click ‘edit’ on the file and copy all its content. This content is consistent across environments, so it’s safe to do so.

5. Paste the copied content into the umbraco-cloud.json file in your local project and push the changes.

After completing these steps, your development environment should be correctly registered across all environments, allowing you to continue your work without any issues.

Before setting up the pipeline in GitHub, make sure that the following steps from the are done:

• Pick a Cloud project

• Activate CI/CD Flow

Next, you will need to define your pipeline in YAML and use it to interact with the Umbraco Cloud API.

Import Cloud project repository to GitHub

Go to your repositories in GitHub and click on "New".

• Create a new empty repository, and note down the clone URL.

• Go to the Umbraco Cloud Portal and clone your cloud project down locally. describes how you can find the clone URL.

• Now working locally remove the Git Remote called origin, which points to Umbraco Cloud

• Optionally rename branch master to main

• Add a new remote called origin and pointing to the GitHub clone URL and push

Now we can move on to setting up a pipeline.

Set up GitHub repository variables

• Now go to the repository in GitHub, and click on the Settings section.

• Expand secrets and variables in the left-hand menu titled Security and click on Actions.

• Create a repository secret called UMBRACO_CLOUD_API_KEY with the API Key value from the Umbraco Portal.

• Create another repository secret with the name PROJECT_ID and the Project ID value from the Umbraco Portal.

Now GitHub is set up with the needed information to be able to run a deployment back to Umbraco Cloud.

Next up it setting up the actual pipeline.

Allow GitHub to commit to your repository

The sample pipelines have a job called cloud-sync. This job is responsible for checking for changes in your Umbraco Cloud project, fetching them, and applying them back to your repository. In order for this to work, you need to give the GITHUB_TOKEN write permissions to the repository during workflow runs.

This is how you can grant these permissions:

• Working in your repository on GitHub, click on Settings in the top right

• In the left sidebar, click on Actions and then on General

• Scroll down to the Workflow permissions sections

• Select the Read and write permissions

• Click save

Set up the GitHub Actions pipeline

Select your preferred scripting language:

The push will start a new pipeline run.

Optional: Test the pipeline

With everything set up, you may want to confirm that Umbraco Cloud reflects the changes you are sending via your pipeline.

While working on you project locally, add a new Document type.

• Commit the change to main branch (or master if you did not change the branch name) and push to your repository.

• The pipeline starts to run

• Once the pipeline is done log into Backoffice on your left-most environment in Umbraco Cloud

• Go to the Settings section and see that your new Document type has been deployed

High level overview of the pipeline components

The mentioned scripts are provided as a starting point. It is recommended that you familiarize yourself with the scripts and with documentation related to how to use GitHub Actions.

The scripts demonstrates the following:

• How to deploy changes to the left-most project environment in Umbraco Cloud

Main

The main.yml is the main pipeline, and is the one that will be triggered on a push to main branch. You can configure a different trigger behavior in this file.

You can add your Build and Test jobs between the cloud-sync and cloud-deployment jobs. Keep in mind that you do not need to retain the dotnet build artifact for upload later. The cloud-deployment job will take care of packaging all your source code and upload to Umbraco Cloud.

Cloud-sync

The cloud-sync.yml shows how you can sync your GitHub repository with the left-most environment of your Cloud project. In this sample, it accepts any change from the API and applies and commits it back to the branch which triggered the pipeline. However the commit does not trigger the pipeline again.

If you don't want the pipeline to commit back to the triggering branch, this is where you need to change the pipeline.

Cloud-deployment

The cloud-deployment.yml show how you can deploy your repository to the left-most environment of your Cloud project. The sample shows how to prepare for deployment, request the deployment and wait for cloud to finish.

There are a couple of things here to be aware of:

• We are overwriting the .gitignore file with cloud.gitignore. This is a way to accommodate your gitignore-needs when working locally. For instance you might want to ignore frontend builds, but you want them build and published to cloud.

• We have a special cloud.zipignore file. This is a convenient way to tell the pipeline which files not to include when creating the zip package to send to cloud.

Further information

In the Umbraco Cloud Settings menu, you can find a page called Usage.

On the Usage page, you will find an overview that displays your usage and evaluates it against the plan limitations of your project. On the page, you will also find the top 10 for the bandwidth usage of your project. This can give you important insight into where you can optimize resource management.

Usage overview

The overview shows the bandwidth of the project for the current month, the media storage size, and the number of custom domains added to the project. It is also possible to see the bandwidth history for the previous six months.

In this overview, you will find the usage limitations for your Umbraco Cloud project as well as the plan that the project is on.

The usage shown is for the Live environment of your project as it is the usage in this environment that is measured against the plan usage limits. For media storage, it is the size of all files in the blob storage including the cache that is considered.

Bandwidth Top 10's

You will find a couple of top 10 for the bandwidth in the project's live environment.

Top 10 - Bandwidth Usage Paths

The first is displaying the 10 resources that are contributing the most to the total bandwidth of your project. Each resource is represented by its path together with the number of requests and its total contribution of bandwidth.

Top 10 - Bandwidth Usage Referrers

The second displays the top 10 HTTP Referrers causing the most bandwidth. A referer is an optional HTTP header field identifying the address of the web page from which the resource was requested. It is the bandwidth generated from these resource requests that counts in the monthly usage limit of the project.

Top 50 - Media Files

It is also possible to see the top 50 media files on your live environment.

The list shows the name of the file, its path, size, and type (whether it is a jpeg or a png file).

Usage limits

You can always upgrade your project to a higher plan if you have reached the limit of what you are allowed on your project. You can Upgrade the Plan from the Management tab on your project.

Leveraging Azure metrics data, the Availability & Performance page provides users with valuable insights into the availability and performance of their cloud project. This enables them to monitor and address any issues that may impact the user experience.

Overview

Under Availability & Performance, you'll find visualization and statistics for three sections:

• Time range and granularity selector

• Panel view

• Chart and statistics view

The visualization and statistics can be seen for all your different environments.

Time range and granularity selector

When entering the page, you'll see a default visualization of failed requests for the last 24 hours with a data point set for every fifth minute. You are able to change the time range to a predefined interval or define a specific start and end time. You can also select the granularity of the data points.

Initially, you will only be able to set the time granularity to “5 minutes”.

Panel view

The panel selector consists of four tiles, each representing a specific segment of data. The four segments are failed request, App Performance, CPU Usage, and Memory Usage.

Each tile includes relevant statistics and potentially a warning or an error indicator in case there is something you might want to consider.

An error indicator is shown in the following situations:

• Failed Requests: when one or more server errors have occurred in the selected time range.

• CPU Usage: when the maximum CPU time has exceeded 100% of the plan quota in 5 minutes during the selected time range.

• Memory Usage: when the maximum private time has exceeded 100% of the plan quota in 5 minutes during the selected time range.

A warning indicator is shown in the following situations:

• Failed Requests: when one or more client errors (but no server errors) have occurred in the selected time range.

• CPU Usage: when the maximum CPU time has exceeded 80% percent of the plan quota in a 5-minute period during the selected time range.

• Memory Usage: when the maximum private time has exceeded 80% percent of the plan quota in a 5-minute period during the selected time range.

Errors and warnings for CPU Usage and Memory Usage are only shown for cloud projects on shared plans with a granularity of 5 minutes selected.

Chart and statistics view

Failed request

The chart shows the breakdown of HTTP status codes for each data point with the selected granularity. Only responses indicating a client (4xx region) or server errors (5xx region) are shown.

In the statistics panel on the right, you will find the total instances of the status code in the time range.

App Performance

The chart shows the average response time during the selected time range. All requests to the Umbraco solution in the time periods with the length of the selected granularity count to average response time.

The statistics panel shows the average, maximum, and minimum response for the shown data points.

CPU Usage

The chart depicts the CPU time consumed by the application in the selected time range with time periods equalling the selected granularity.

• The maximum CPU time

• The average CPU time

• The plan quota

• The maximum and average percentage of the consumed CPU in a 5-minute period compared to the plan quota.

Cloud projects on dedicated options (or a shared plan with another granularity than 5 minutes), users will see the average assigned CPU time in seconds. Here the statistics panel will display the maximum, average, and minimum CPU time based on selected granularity.

Memory Usage

The chart shows the memory usage in private bytes consumed by the application in the selected time range with time periods equalling the selected granularity.

For cloud projects with a dedicated option (or shared plans with another granularity than 5 minutes), users will see the average assigned private bytes in bytes. Here the statistics panel will display the maximum, average, and minimum allocation of private bytes based on selected granularity.

Platform and CMS events

The charts are enhanced with platform events like restarts, automatic and manual upgrades, environment-to-environment deployments, and plan changes.

This information will help you in potential troubleshooting, make informed decisions, and ensure smooth project management.

By utilizing the Umbraco.Cloud.Cms package we are tracking the hot and cold boots of your Umbraco environment on Cloud.

The package is installed on all environments running Umbraco 10, 13, and 14 on Umbraco Cloud. The package will be part of new Cloud projects on upcoming versions of Umbraco CMS.

You can disable Hot/Cold boots tracking on your Umbraco Cloud Project by adding Umbraco:Cloud:DisableBootTracking and set to true in the appsettings.json file.

It is also possible to remove the reference to the Umbraco.Cloud.Cms package in the UmbracoProject.csproj.

Key benefits

Below you can read about the benefits the Availability & Performance page gives.

Health Monitoring

The page allows users to monitor the health of their cloud projects more effectively. By leveraging Azure metrics data, you can access critical information such as HTTPS status codes, response times, CPU time, and memory usage in private bytes.

The CPU and memory usage is particularly important to keep an eye on from time to time. This is to ensure the cloud project running on a shared that the plan quotas aren’t exceeded.

Issue Discovery

The page enables users to discover application issues that may impact the overall performance of their Umbraco Cloud projects. By analyzing Azure metrics data, you gain valuable insights into the performance of your app service, including response times and CPU/memory usage.

Real-time monitoring of HTTPS status codes helps you identify any errors or disruptions to your application's availability. This proactive approach allows you to respond swiftly, ensuring that your website or application remains accessible and responsive to users.

User-Friendly Interface

Umbraco Cloud provides a user-friendly interface for accessing and interpreting the "Availability and Performance" page. The interface presents Azure metrics data in a clear and understandable manner, making it easier for users to navigate and gain actionable insights. With intuitive SVG-based visualizations and highlighted statistics for the selected time range, you can monitor the health and performance of your cloud projects effortlessly.

Future updates

The first version of the “Availability and Performance” feature released on May 26th, 2023 includes a basic visualization and a set of highlighted numbers for failed requests, application performance, CPU time, and memory usage.

More detailed information about each of these domains will be provided for each of the four domains in the future. While the visualization and basic numbers are accessible for any project plan, the detailed information and insight to be added will be exclusive to the upper cloud project plans

There are two ways to add secrets to your Cloud project, as an Environment Secrets or as a Shared Secrets.

Environment Secrets are intended to be utilized exclusively within a particular environment during the runtime of your Umbraco solution.

Shared Secrets are utilized across all environments and will be seamlessly integrated into any new environment you create. Shared Secrets are particularly well-suited for safeguarding credentials necessary for project development, such as access to private NuGet feeds.

Typical secrets are Private Keys, 3rd-party API tokens, database passwords, or otherwise sensitive data that needs to be kept secret.

When the secrets have been added they will be exposed exclusively to the assigned environments.

It will be assigned as an environment variable at runtime using the assigned name for the secret.

It will then use a reference that only the managed identity of the environment has access to.

How to add secrets

To add a secret to your environment follow these steps:

1. Go to your Umbraco Cloud project

2. Go to the settings section and go to Secret Management

3. Choose either shared or environment secrets

4. Choose the environment to add the secret and click Add secret

5. Add the Key and the Value in the fields and click Add secret

6. Save the key to the environment.

Working locally with secrets

When you develop locally, you cannot access secrets that are stored in the key vault associated with a cloud environment.

We recommend that you use common methods for handling secrets locally, such as using app settings in the appsettings.development.json.

The app setting should not be committed to the code repository or it needs to be ignored via a gitignore file.

An example could be that you have a secret in a cloud environment with the key name "ApiKey",

You should specify this with a corresponding name in a configuration file such as appsettings.development.json:

{
   “Serilog”: {
     …
   },
   “Umbraco”:{
     …
   },
   “ApiKey”: “Value”,
}

Access secrets in a Umbraco Solution

Secrets for cloud environments are stored in a key vault and loaded by the app service (using a key vault reference) as an environment variable.

This enables you to get the value at runtime as you normally would fetch an environment variable.

You can use the method, getting it from the System namespace in .NET as below:

_secretMessage = Environment.GetEnvironmentVariable("SecretMessage");

Secrets can also be used to override AppSettings defined in appsettings.json files.

In order for this to work, when adding the secret, the Key value should be all the settings' names joined by double underscores.

For example, to change the Serilog's default options under Serilog:MinimumLevel:Default, the Secret key would look like this:

Serilog__MinimumLevel__Default

The value defined in appsettings.json file will be overwritten with the Cloud Secret's value.

Naming standards for secrets

When naming a secret, it is possible to use alphanumeric characters as well as '_' (underscore).

Some words are reserved and cannot be accepted:

• COMMAND

• HOME

• PORT

• REMOTE

• DEBUGGING

• VERSION

• REGION_NAME

• CONNECTIONSTRINGS__UMBRACODBDSN

The following prefixes are not accepted.

The list consists of:

• UMBRACO_

• WEBSITE_

• SCM_

• SDEPLOY_

• DEPLOYMENT_

• DOCKER_

• CONTAINER_

• DIAGNOSTICS_

• APPSERVICEAPPLOGS_

• WEBSITE_

• DOTNET_

• IDENTITY_

• MSI_

• WEBJOBS_

• FUNCTIONS_

• AzureWebJobsWP_

• PHP_

• FILE_

• DATABASE_

• WORDPRESS_

• MACHINEKEY_

• SQLCONNSTR

• SQLAZURECONNSTR_

• POSTGRESQLCONNSTR_

• CUSTOMCONNSTR_

• MYSQLCONNSTR_

• AZUREFILESSTORAGE_

• AZUREBLOBSTORAGE_

• NOTIFICATIONHUBCONNSTR_

• SERVICEBUSCONNSTR_

• EVENTHUBCONNSTR_

• DOCDBCONNSTR_

• REDISCACHECONNSTR_

• FILESHARESTORAGE_

Accepted Prefixes

The following prefixes are allowed for Secrets on Umbraco Cloud:

• Umbraco__CMS__Global__Smtp__

• Umbraco__Forms__Security__FormsApiKey__

• Umbraco__Forms__FieldTypes__Recaptcha__

• Umbraco__CMS__Integrations__

• Umbraco__CMS__DeliveryAPI__

• UMBRACO__LICENSES__

It is also possible to use Secrets to save API keys, Passwords, and ReChaptcha for all our Umbraco products on Umbraco Cloud.

Do you have an existing or new secret that you want to add to a key vault that conflicts with the name restrictions?

Then please contact Umbraco support, then we will consider it as soon as possible.

The Project History page shows details about the following changes to your project:

• Project plan.

• Transitions between shared and dedicated resources.

• Adding or removing environments.

• Deployments.

• Product upgrades.

This is to provide you with better oversight and control over your project.

For each activity you can see the following information:

• The type of activity

• Information about the activity

• Who the activity was started by

• When the activity was started

• When the activity ended

• The status of the activity

To get a detailed view of each history type on your project, click the info icon on the far right of the history activity.

If you click on the info icon for an automatic update, you will be redirected to an Upgrade Details page. On this page, you can see details about how the upgrade went.

For activities like adding and removing environments, clicking on the info icon will show details of how the process went when adding/ removing the environment.

One of the biggest benefits of having a Umbraco Cloud project is that you do not need to worry about the hosting. We handle it for you.

When we do maintenance on our Umbraco Cloud servers, we send out information to all our Umbraco Cloud customers. For us to reach out to the correct person, you need to add a Technical Contact to your project.

When you create a New Project, the user used to create the project will automatically be added as the technical contact. To update the technical contact or add more than one technical contact, do the following:

1. Go to the Project in the Umbraco Cloud Portal.

2. Go to Edit Team in the Overview menu tab.

3. Click Add Technical Contact in the Technical Contact section.
4. Enter the Name, Email, and Telephone Number in the Add New Technical Contact window.
5. Click Confirm.

This article is about team members that are added via the Invite User button in the Umbraco Cloud Portal. If you are looking for more information about Users in the Backoffice, see Users. Users added through the backoffice do not have access to the Umbraco Cloud Portal.

Team members are users that you add to your project via the Invite User button in the Umbraco Cloud Portal. They are automatically added as users in the Backoffice of all environments for the project. These users can clone down the project locally and log in using the same credentials they use for Umbraco Cloud.

When adding a user, the default permission is Read for each environment. You can assign backoffice user groups to the user for each environment.

Team Member User Permissions

User Permissions for each environment can be set in the Edit Team page available from the Settings dropdown. User Permissions can be set per environment. For example, a user can have Write access on the Development environment and Read access on the Live environment.

• Admin: Has access to everything on a project. An admin can delete a project and edit the team. An admin can deploy changes between environments in the Project Portal and has access to git, as well as the Power Tools Kudu.

• Read: A team member with Read permissions can only view the project in the portal as well as the backoffices. They are not able to deploy or change anything on the project itself. They can clone down the project, but cannot push changes they have made locally. By default, they are added as an admin in the backoffice so they can make changes in the backoffice. If you want to change this, see Team Member Permissions in the Umbraco Backoffice below.

• Write: A team member with Write permissions can do everything on a project except delete it and edit the team. A user with Write permissions can deploy changes between environments through the portal. They have access to the git repositories and can push local changes to the environment.

• No Access: A team member with No access permissions cannot restart the environment, deploy changes between environments, check error logs or log files, or access Kudo in the Project Portal. They can view the project in the portal and access the backoffice.

Backoffice User Groups for Team Members

You can view the user group memberships of the project’s backoffice users. Currently, you can manage the backoffice user groups of a user through the Umbraco backoffice. A backoffice user is only created once the user logs into the backoffice of the project for the first time.

Team Members Pending Invitation

You can see the details of your project invitation in the Member(s) who still needs to accept the project invitation section of the Edit Team page. You can view the team member's name, email, the expiration date of the invitation, the status of the invitation, copy the invitation link, resend the invitation, or delete the invitation.

Technical Contacts

For us to reach the correct person when sending out information about server maintenance, you need to add a technical contact to your Umbraco Cloud project.

To manually upload your certificate on the Umbraco Cloud Portal and assign it to one of the hostnames you've added:

1. Go to your project on the Umbraco Cloud portal.

2. Click Settings -> Certificates. The Manual Certificates window opens.

Your certificates need to be:

1. In .pfx format.

2. Must use a password.

3. Cannot be expired.

4. Signature algorithm must be SHA256WithRSA, SHA1WithRSA or ECDSAWithSHA256

The .pfx file can only contain one certificate. Each certificate can then be bound to a hostname you have already added to your site. Make sure you use the hostname you will bind the certificate to as the Common Name (CN) when generating the certificate.

Add Manual certificate

1. Click Add New Certificate.

2. Select Choose file in the Certificate (.pfx file) field and upload your certificate from your local machine.

3. Enter the Password for your certificate.
4. Click Add.

Bind Certificate to a Hostname

1. Click Add new binding.

2. Choose your hostname from the Hostname dropdown.

3. Choose your newly uploaded certificate from the Certificate dropdown.

4. Click Add.

You've now successfully added your certificate to the Cloud project.

From Custom Certificate to Automatic TLS (HTTPS)

In some cases, you might want to switch from using your custom certificate to using the ones provided by the Umbraco Cloud service.

By removing your certificate from your Cloud project, the Umbraco Cloud service will automatically assign a new TLS (HTTPS) certificate to the hostname.

Read more

• Redirect from HTTP to HTTPS