Decoupled Deployments Are GA: Stop Rebuilding the CM for a CSS Change

This one’s been in beta for a while, and as of yesterday (January 29th) it’s official: decoupled deployments are generally available in SitecoreAI, and they’re on by default for every new project.

If you’ve ever waited for a full CM build and deploy because someone changed a button color in the head app, this is the feature you’ve been waiting for.

Coupled vs decoupled, quickly

Coupled (the legacy model): the authoring environment (CM) and the editing host are built and deployed together. Change anything in the repo and you get a full build, a CM deployment and an editing host deployment. One log, one pipeline, one long coffee break.

Decoupled: the CM and each editing host are built and deployed separately. That gets you:

• Front-end changes deploy without rebuilding or restarting the CM
• Each editing host can live in its own Git repository
• Separate logs per component (finally)
• Less compute and search index churn from deployments that didn’t need to touch the CM

For multi-site setups with a few head apps sharing one CM, this is a big quality-of-life upgrade.

How the pieces fit together

The build config still lives in xmcloud.build.json. The editing host side is driven by the renderingHosts section. Here’s a trimmed example of the shape (check the build configuration docs for the full property list):

{
  "renderingHosts": {
    "corporate": {
      "path": "./headapps/corporate",
      "nodeVersion": "22.11.0",
      "jssDeploymentSecret": "<set in your secrets, not here>",
      "enabled": true,
      "type": "sxa",
      "buildCommand": "build",
      "runCommand": "next:start"
    }
  },
  "deployItems": {
    "modules": ["Foundation.*", "Feature.*", "Project.*"]
  }
}

The important bit for decoupled: when you set up an editing host in the Deploy app with your own code, the Editing host name you enter has to match a key under renderingHosts in the xmcloud.build.json of that editing host’s repo. In the example above that’s corporate.

A couple of gotchas from the docs worth calling out:

• Don’t name a custom editing host default. It’s reserved.
• The editing host build runs in a restricted environment. Any file read/write has to happen inside the working directory, so build scripts that write to temp folders elsewhere will fail.
• If you leave out deployItems, every module in your sitecore.json gets converted to IAR files. Be explicit.

Converting an existing project

Existing projects keep working as-is. Redeploying a coupled project leaves it coupled. But the coupled model is now legacy, and future improvements are aimed at decoupled, so you’ll want to move.

There’s a Convert option in the project settings in the Deploy app. Before you click it, here’s the checklist I’m using:

1. Do it on a non-prod environment first. Convert, deploy, edit a page in Page builder, publish. Make sure the round trip works.
2. Audit your editing host environment variables. With decoupled deployments the editing host is its own thing with its own variables. Anything that was “inherited” from the coupled setup needs to be set explicitly on the editing host.
3. Check your branching strategy. Separate deploys mean the CM and the head app can be on different commits. That’s the point, but make sure your team knows which branch deploys what.
4. Decide on repo structure. Mono-repo is still fine. If you split the editing host into its own repo, plan how serialized items and front-end code that depend on each other get released together.
5. Update your runbooks. “Redeploy the environment” doesn’t mean what it used to.

Should you split the repos?

Not necessarily. Here’s my rule of thumb:

• One site, one team: keep the mono-repo. Decoupled deployments still buy you faster front-end deploys and better logs.
• Multiple sites, different teams or release cadences: split them. Letting the marketing site ship daily without waiting on the intranet team’s sprint is exactly what this was built for.

Either way, this is one of those features that just makes the day-to-day better. Faster deploys, clearer logs, fewer “why did the CM restart?” messages in Teams.

Resources

• Decoupled deployments is now generally available: https://developers.sitecore.com/changelog/sitecoreai/29012026/decoupled-deployments-is-now-generally-available
• Deploy a project and environment: https://doc.sitecore.com/sai/en/developers/sitecoreai/deploy-a-project-and-environment.html
• The SitecoreAI build configuration: https://doc.sitecore.com/sai/en/developers/sitecoreai/deploying-sitecoreai/the-sitecoreai-build-configuration.html