Decoupled deployments have recently been made generally available, so now is a good time to consider converting your project. I have recently run through the process and would like to share some thoughts and gotchas I encountered along the way.

What are "Decoupled Deployments"?

Before talking about how to convert, first let's review why we want to do this in the first place. Up until now, SitecoreAI editing hosts were a part of the same monolithic repository. 
 

This meant that the code for each head was stored in the same place. This also meant that to deploy changes to one of the heads you had to deploy not only the entire CMS solution, but also every other head app too. This violates the Separation of concerns practice as well as slows down development time waiting for long builds.

The decoupled deployments solve these issues. With decoupled deployments, the CMS repository is separate from each head app. They get their own code repositories and build pipelines. 
How to convert your existing project

Sitecore does provide a pretty simple pathway to conversion, as well as a one click button. However, I did find a couple small gotchas and considerations along the way.

Step 1: Preparation

Before you click convert project from the SItecoreAI Deploy dashboard, make sure to review your code for all branches and environments. The process will build and deploy every environment in the project including production.

Gotcha 1: Separate your code before converting

You can do this after the fact, and it causes no issues to not do it, but it would make the most sense to pull your head app code out of the CMS repository and into its own repository before you deploy. If you don't do this, when the conversion takes place, Sitecore will build and deploy all your code and create rendering hosts using the build config in repository. It basically puts you in a state where the deployments are separated, but all the code still exists in the same repository. If you want to change this after, you will need to make changes to the code/repository and deploy everything again. It is best to just do this all at once.

1. Create a new repository with just the head code.

2. Delete the head code from the CMS.

3. Convert and deploy.

Gotcha 2: Make sure to configure your xmcloud.build.json

If you are not familiar with the xmcloud.build.json, it is a pretty simple file that, among other things, configures the rendering hosts for your project. Previously, when the head apps were inside the solution it was straight-forward.

   "basic-nextjs": {
     "path": "./examples/basic-nextjs",
     "nodeVersion": "22.22.0",
     "jssDeploymentSecret": "110F1C44A496B45478640DD36F80C18C9",
     "enabled": true,
     "type": "sxa",
     "buildCommand": "build",
     "runCommand": "next:start"
   },

However, now that the app is not inside this repository, we still need a configuration here to tell Sitecore what the website name is. We also need to include this file in our separate head app repository. In the CMS repository, it should look like this. 

"basic-nextjs": {
                              "path": "."
               }

And in the head repo it should look like this:

   "basic-nextjs": {
     "path": ".",
     "nodeVersion": "22.11.0",
     "enabled": true,
     "type": "sxa",
     "buildCommand": "build",
     "runCommand": "next:start"
   }

This site's definition needs to exist in both places, and the names must match.

Step 2: Conversion

After you have made these changes, you are ready to click the magic button.
 

Like it says here, data will not be affected, but it will build and deploy all environments.

Gotcha 3: The conversion build/deploy does run serialization sync

I wasn't sure if this was the case, so I made sure to test this and I have confirmed that the build & deploy run by the conversion agent does run the serialization sync. If you have any serialization configurations in your solution, they will run. Make sure this is all up to date and will not be overwriting or changing any serialized items in your instance.

Depending on the number of environments, this could take a long time. If any build fails at this point, it will automatically re-try. If you have your rendering hosts configured correctly inside your build file, it should also automatically create those deployments as well.

Step 3: Validation

Assuming the build and deploys all went smoothly, you should now see two tabs inside your project page instead of one.
 

Authoring environments are now completely separate from rendering hosts. If you check the details, they should be pointing to your CMS repository.
 

While the editing host has its own configuration. 
 

If this is all configured correctly, you will now be able to make changes to your editing host, like adding a component or changing styling, and deploy it independently. These deployments are much faster and do not run the full CMS deploy.
 

• Only the changed editing host is deployed.

• Other hosts (if configured) do not get deployed.

• CMS deployment does not run

• No content serialization sync.

I hope this helps with your conversion journey!