Cross Cloud Deployment Patterns

Cross-Cloud Deployment Patterns

This skill activates when a practitioner or agent must deploy metadata that spans multiple Salesforce clouds — typically Sales Cloud or Service Cloud combined with Experience Cloud — and must resolve dependency ordering to prevent cascading reference errors. It covers the mandatory foundation-first deployment sequence, ExperienceBundle and DigitalExperienceBundle exclusion rules, and API version compatibility constraints.

Before Starting

Gather this context before working on anything in this domain:

• Identify every metadata type in the deployment package. Group them into three layers: (1) foundation objects and Apex, (2) Network and site infrastructure, (3) Experience layer (ExperienceBundle or DigitalExperienceBundle).
• Confirm source and target org API versions. Certain Experience Cloud metadata types are not backward-compatible. The target org must be on the same API version as or a newer API version than the source org.
• Check whether SiteDotCom is included in the package. If it is embedded inside an ExperienceBundle, it must be excluded from the deployment even when everything else in the package is valid. Including it causes deployment failure.
• Determine whether the deployment will go in a single transaction or must be split across multiple batches. Reference errors at the Experience layer almost always require a split sequence.

Core Concepts

Foundation-First Sequence

The Metadata API processes types in a documented internal order, but cross-cloud deployments introduce explicit ordering requirements that the engine cannot resolve automatically when dependencies span cloud domains.

The canonical sequence is:

1. Foundation layer: custom objects, custom fields, Apex classes, Apex triggers, Lightning components, permission sets, and profiles.
2. Network infrastructure layer: Network and CustomSite metadata types. These must exist in the target org before any Experience layer component can reference them.
3. Experience layer: ExperienceBundle or DigitalExperienceBundle. These types embed references to the Network record by name. If the Network does not exist in the target org when the ExperienceBundle lands, the deployment fails with the error no Network named X found.

Deploying these three layers in a single transaction is possible only when the Metadata API's internal ordering guarantees that Network and CustomSite are fully committed before ExperienceBundle is evaluated. In practice, the safest approach is to split the deployment into two or three ordered transactions.

ExperienceBundle vs DigitalExperienceBundle

Salesforce introduced DigitalExperienceBundle in API version 54.0 as the successor to ExperienceBundle for Experience Builder sites. The two types are not interchangeable across API versions:

• ExperienceBundle is available from API v45.0 and covers earlier Experience Cloud sites.
• DigitalExperienceBundle is required for sites built with the newer Digital Experiences framework (API v54.0+).

When the source org is on API v54.0+ and the target org is on an older version, DigitalExperienceBundle metadata is not recognized in the target and the deployment fails. Always confirm both org API versions before attempting a cross-cloud deploy that includes Experience Cloud sites.

SiteDotCom Blob Exclusion Rule

SiteDotCom is a binary blob that Salesforce auto-generates when you retrieve certain Experience Cloud site metadata. It is not deployable as part of a standard Metadata API deployment package. Including it — even unintentionally — causes a deployment failure that can be mistaken for an unrelated error. The fix is to explicitly exclude the SiteDotCom type from package.xml and from any .forceignore or .gitignore files that might accidentally allow it to be staged.

API Version Compatibility Constraint

The target org cannot be on an older API version than the source org when Experience Cloud metadata is in scope. Unlike most metadata types that degrade gracefully, Experience Cloud metadata types may reference internal references, page layout formats, or component capabilities that do not exist in older API versions. Deploying across a version boundary in this direction fails silently on some components and loudly on others.

Common Patterns

Split Deployment Pattern (Recommended)

When to use: Any cross-cloud deployment that includes ExperienceBundle, DigitalExperienceBundle, or CustomSite alongside foundational metadata like custom objects, Apex, or permission sets.

How it works:

1. Build a foundation-package.xml that includes: CustomObject, ApexClass, ApexTrigger, LightningComponentBundle, PermissionSet, Profile.
2. Deploy the foundation package and wait for it to complete successfully.
3. Build a network-package.xml that includes: Network, CustomSite.
4. Deploy the network package and wait for it to complete successfully.
5. Build an experience-package.xml that includes: ExperienceBundle or DigitalExperienceBundle. Explicitly exclude SiteDotCom.
6. Deploy the experience package.

Why not a single package: A single-transaction deploy of all three layers risks the Experience layer being evaluated by the Metadata API before the Network record is fully committed, which produces the no Network named X found error regardless of whether the XML is otherwise valid.

Single-Transaction Pattern (Low-Risk Releases)

When to use: Small releases where only ExperienceBundle page layout changes or content updates are included and the foundation layer already exists and is stable in the target org.

How it works: Deploy only the Experience layer changes in a single package. The Network and CustomSite records already exist in the target org, so no cross-layer dependency needs to be resolved.

Why not always: If foundation components are also changing in the same release, this pattern breaks. Foundation changes must land first.

Decision Guidance

Recommended Workflow

Step-by-step instructions for an AI agent or practitioner working on this task:

1. Audit the full component list. Enumerate every metadata type in the release. Group each type into foundation, network, or experience layer. Flag any SiteDotCom entries for exclusion.
2. Check API version alignment. Confirm source org API version equals or is less than the target org API version. If the target is behind, escalate to the platform admin before proceeding.
3. Build the foundation package. Assemble a package.xml containing all custom objects, Apex classes, Apex triggers, Lightning components, permission sets, and profiles. Exclude Network, CustomSite, ExperienceBundle, DigitalExperienceBundle, and SiteDotCom.
4. Deploy foundation and validate. Run sf project deploy start --manifest foundation-package.xml --target-org <alias>. Confirm full success before advancing. Do not proceed if any component fails.
5. Deploy the network layer. Assemble and deploy a package containing Network and CustomSite. Verify the Network record is queryable in the target org after deployment (sf data query --query "SELECT Id, Name FROM Network" --target-org <alias>).
6. Deploy the experience layer. Assemble and deploy a package containing ExperienceBundle or DigitalExperienceBundle. Confirm SiteDotCom is absent from the manifest. Monitor the deploy for no Network named X found errors — if they appear, the network layer did not fully resolve before the experience layer was submitted.
7. Run post-deployment validation. Verify site availability, navigate to community pages, confirm permission sets grant the expected access, and run automated smoke tests against the target org.

Review Checklist

Run through these before marking work in this area complete:

• All metadata components classified into foundation, network, or experience layer
• SiteDotCom excluded from every deployment package
• Target org API version confirmed equal to or newer than source org API version
• Foundation layer deployed and validated before network layer starts
• Network layer deployed and validated before experience layer starts
• ExperienceBundle or DigitalExperienceBundle deployed without SiteDotCom
• Post-deployment site availability and permission checks passed

Salesforce-Specific Gotchas

Non-obvious platform behaviors that cause real production problems:

1. no Network named X found appears even when Network is in the same package — The Metadata API can evaluate ExperienceBundle before Network is committed within a single transaction. This error is not a missing-component error; it is an ordering error. The fix is to split Network into a prior deployment batch.
2. SiteDotCom is silently included in retrievals — When you run sf project retrieve start and include ExperienceBundle in the manifest, Salesforce may return SiteDotCom as part of the result set. It does not appear as an error during retrieval but causes a deployment failure if included in the deploy manifest. Audit retrieved metadata before packaging.
3. DigitalExperienceBundle is version-locked — Unlike most metadata types that degrade gracefully across API version differences, DigitalExperienceBundle does not deploy to a target org on a lower API version. The deployment fails without a clear actionable error message pointing to the version mismatch.

Output Artifacts

Related Skills

• pre-deployment-checklist — use for pre-flight validation across any Salesforce deployment before executing the sequence
• permission-set-deployment-ordering — use when permission sets in the foundation batch require precise ordering to avoid cross-reference errors
• experience-cloud-deployment-dev — use for Experience Cloud-specific developer configuration and LWR or Aura component deployment details
• experience-cloud-deployment-admin — use for admin-level Experience Cloud setup, Network settings, and guest user access configuration
• post-deployment-validation — use after the experience layer is deployed to verify site availability and access
• metadata-api-coverage-gaps — use when unexpected metadata types are missing from the deployment or not behaving as documented