Getting Started with Content Sync in Xperience by Kentico

If you've ever maintained multiple Xperience by Kentico environments side by side, you've felt the friction. Editors approve content on staging, developers validate the output, and then someone has to figure out how to reliably move everything to production without breaking anything. For a long time, that "figuring out" step was the messy part.

Content Sync changes that. It's a built-in feature in Xperience by Kentico that gives you a structured, reliable way to push content from one environment to another, without workarounds, manual exports, or crossed fingers.

This post walks through what Content Sync is, the requirements you need to meet before configuration, and exactly how to wire it up in your Program.cs.

What Is Content Sync?

Content Sync is a first-party mechanism for transferring content items between Xperience by Kentico environments. The most common use case is a staging-to-production workflow: content gets created and reviewed on a staging server, and once approved, it gets synchronized to the live site.

The design is intentionally simple. It operates as a one-to-one connection between a source environment and a target environment. One server pushes content out, one server receives it.

This simplicity is a feature, not a limitation. It keeps the data flow predictable and auditable, which matters a lot when content accuracy is business-critical.

Prerequisites

Before you write a single line of configuration, there are three requirements you need to confirm. Skipping any one of them will prevent the sync from working.

1. Version Parity

Both the source and the target environments must run the same version of Xperience by Kentico, including hotfixes. Version mismatches can cause silent failures or data inconsistencies. If you've recently applied a hotfix to production, make sure staging matches before attempting a sync.

2. HTTPS on the Target

The receiving environment must be accessed over HTTPS. Content Sync transfers data between servers across the network, and using an unencrypted connection for this transmission is unacceptable. If your target system is still operating on plain HTTP, you will need to address that issue before proceeding.

3. A Valid License

Both environments need a current, valid Kentico license. An expired or missing license will block the feature from initializing correctly.

Configuration

Content Sync is configured entirely in code, inside your Program.cs files. There are no admin UI settings to toggle. The source and target each get their own configuration block, built around the ContentSynchronizationOptions class.

Source Server Configuration

The source is the environment that sends content out. Add the following to the Program.cs of your staging (or source) server:

builder.Services.Configure<ContentSynchronizationOptions>(options =>
{
    options.Source.Enabled = true;
    options.Source.Secret = "SECRET_KEY"; // At least 32 characters; must match the target
    options.Source.TargetUrl = "URL_THAT_WILL_RECEIVE_THE_SYNCED_CONTENT"; // Example: https://yourproductionsite.com
});

A few things worth noting here:

• Secret must be at least 32 characters long. This shared key is how the two servers authenticate the sync request. Use a strong, randomly generated value.
• TargetUrl should point to the root URL of your production environment, served over HTTPS.
• Enabled = true activates the source behavior on this instance.

Target Server Configuration

The target is the environment that receives incoming content. Add this to the Program.cs of your production (or target) server:

builder.Services.Configure<ContentSynchronizationOptions>(options =>
{
    options.Target.Secret = "SECRET_KEY"; // Must match the source server exactly
    options.Target.Enabled = true;
});

The Secret value here must be identical to the one configured on the source. This is how the target validates that incoming sync requests are legitimate.

Environment-Aware Configuration

In real projects, you typically want to avoid maintaining two entirely separate Program.cs files. If your environments support automatic instance detection through environment variables, you can use standard ASP.NET environment checks to consolidate both configurations into a single file:

// Configures the development environment as the content sync source
if (builder.Environment.IsDevelopment())
{
    builder.Services.Configure<ContentSynchronizationOptions>(options =>
    {
        options.Source.Enabled = true;
        options.Source.Secret = "SECRET_KEY"; // At least 32 characters; must match the target
        options.Source.TargetUrl = "URL_THAT_WILL_RECEIVE_THE_SYNCED_CONTENT"; // Example: https://yourproductionsite.com
    });
}

// Configures the production environment as the content sync target
if (builder.Environment.IsProduction())
{
    builder.Services.Configure<ContentSynchronizationOptions>(options =>
    {
        options.Target.Secret = "SECRET_KEY"; // Must match the source server exactly
        options.Target.Enabled = true;
    });
}

This approach keeps your startup code clean and ensures that only the relevant configuration block activates for a given environment. The IsDevelopment() and IsProduction() checks are driven by the ASPNETCORE_ENVIRONMENT variable, so as long as that's set correctly on each server, you won't accidentally enable source behavior on production or vice versa.

Deploying and Testing

Once you've updated the configuration, the process is straightforward:

1. Push the updated Program.cs to both servers.
2. Restart both instances so the new configuration is picked up.
3. From the Xperience administration interface on the source environment, initiate a content sync operation.
4. Confirm the content appears on the target environment as expected.

If something doesn't sync correctly, the first things to check are version parity between the two environments, whether the Secret values match exactly, and whether the target is accessible over HTTPS from the source server's network.

Why This Matters

Content Sync is one of those features that removes an entire category of operational risk. Manual content migration between environments is error-prone, undocumented, and impossible to audit. With Content Sync, the process is explicit, repeatable, and controlled.

For teams managing enterprise Kentico implementations, this is the foundation of a reliable content promotion workflow. Get this right, and your editors can focus on the content instead of worrying about whether their changes will make it to production intact.

At Simple [A], our team of certified Kentico developers and architects helps clients build content systems that are not just functional, but operationally sound. Whether you're setting up a new environment topology or untangling an existing one, we can help you get there.

Want to talk through your Xperience by Kentico setup? Let's connect.