Source control on Umbraco Cloud – are you doing it right?

Umbraco Cloud lets you push your code directly to the repository that Cloud gives you – but just because you can do it, doesn’t necessarily mean you should.

Mario Lopez

20 May 2024

4 minute read

Umbraco Cloud is the same Umbraco flavour that you can use and host yourself but hosted by Umbraco HQ, the people behind the development of Umbraco.

It gives you a very-easy-to-setup site, that you can spin up in five minutes. It also gives you the opportunity to enable automatic upgrades and other perks, like managed security, CDN or free TLS certificates.

To develop a website with Umbraco (whether it’s hosted by you or by Umbraco themselves) you have the option to do it from the back office.

While Umbraco does offer you tools that allow you to configure and develop your site from the back office, if your website is not extremely simple, you will soon realise that the best way to develop with Umbraco is by having a local copy on your computer and using some IDE like Visual Studio.

Using GIT for deployments

If you follow the Umbraco Cloud documentation to set up your local environment, you’ll be ready to rock in no time.

But eventually, you’ll come to the point when you need to deploy your changes to the Cloud. Again, the Umbraco docs are your friend, but there are some details about how the deployments are approached on the docs that might cause you some issues.

Umbraco docs: Umbraco Cloud uses a deployment model that relies on Git, Kudu, and Umbraco Deploy core technology to move your changes from one environment to another.

When you set up your local clone, you need to get the code from the repository where  Umbraco Cloud stores the raw code. This is done by pulling the master branch of the Cloud repository.

If you make changes to your code and push them to the same branch, this same repository is used to first deploy to the Umbraco Cloud Development environment.

So far so good… but there’s a catch.

Repositories in a Cloud project

When I first started working on a Cloud project, there’s a page that I totally missed which contains very important notes about how to work with your own code on Umbraco Cloud.

Important note (taken from the Umbraco docs):

Ideally, your Umbraco Cloud setup should look like this:

  • A source control repository with your own code
  • An Umbraco Cloud source control repository with the locally cloned Umbraco project

Wait, what!? What do you mean I need two repositories? Didn't you just say that if I push to the master branch of the Umbraco Cloud repository my changes will be deployed to Development?

It turns out that you shouldn’t store your code in the Cloud repository. That repo should be used only to deploy changes. That’s it.

The reason is that the Cloud repo has two disadvantages:

  • Only the master branch is guaranteed to be maintained. Any other branches that you create can be wiped out without warning.
  • The build pipeline can only build dlls from C# code, but you have to precompile other things like any Javascript files you might use for your frontend.

Working with two repositories

Working with two repositories makes things a bit more complicated. Because you need to push your changes to two different places, the recommended approach is to set up CI/CD and use your own pipelines to deploy to Cloud instead of pushing your changes directly to the Cloud repo for deployments.

You will need to add two remotes to your GIT, one to pull from Cloud and the other one to push to your repo.

Pipelines

Supporting automatic upgrades

If you enable Umbraco Cloud’s automatic upgrades, it is very important that you create the branch that you will push to your repo directly from Cloud’s master branch, instead of a new master branch from your repo.

When Cloud upgrades a site automatically, it creates a commit onto the master branch. Next time you need to commit any new changes to your code, you will first need to merge these changes Cloud did or you won’t be able to deploy.

For this reason, if you create an unrelated branch you won’t be able to merge Cloud’s changes into your branch because the histories of both branches don’t match (yeah, I learnt this the hard way).

Remotes

Conclusion

Umbraco Cloud is very convenient and the fastest way to get an Umbraco site up and running. You can always push your code changes directly to the repository that Cloud gives you – I recommend this approach for basic sites and when you are not working with a team of developers.

The recommended approach though is to keep your code in a separate repository and use CD/CI pipelines to deploy to Cloud. Umbraco provides example scripts and explanations to set up Azure Pipelines or Github actions.

Want to work with an Umbraco Platinum Partner?

Contact Us

Keep Reading

Want more? Here are some other blog posts you might be interested in.