SfSkills Domains Docs GitHub

Home / devops / cross-cloud-deployment-patterns

cross-cloud-deployment-patterns

Use when sequencing a deployment that spans multiple Salesforce clouds — Sales Cloud, Service Cloud, and Experience Cloud — and encountering reference errors, cascading metadata failures, or DigitalExperienceBundle ordering problems. NOT for single-cloud deploys (use devops/pre-deployment-checklist) or Health Cloud specifics — use devops/health-cloud-deployment-patterns.

Open the skill folder on GitHub

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:

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:

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

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

SituationRecommended ApproachReason
Full multi-cloud release with new objects, Apex, and new Experience siteThree-batch split: foundation → network → experienceGuarantees cross-layer dependencies resolve in order
Only Experience layer content updates, foundation stableSingle experience-layer batchNetwork already exists; no ordering risk
Source org on API v54+, target org on older versionBlock deployment until target is upgradedDigitalExperienceBundle is not backward-compatible
SiteDotCom appears in retrieved metadataExclude via package.xml and .forceignore before packagingIncluding it causes deployment failure
Network metadata and ExperienceBundle must go togetherDeploy Network first, then ExperienceBundle in sequenceExperienceBundle references Network by name
Permission sets grant access to objects in the same releaseInclude permission sets in the foundation batch, not experience batchObject must exist before permission grants can resolve

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:

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

ArtifactDescription
foundation-package.xmlManifest for the first deployment batch: custom objects, Apex, components, permission sets, profiles
network-package.xmlManifest for the second batch: Network and CustomSite metadata only
experience-package.xmlManifest for the third batch: ExperienceBundle or DigitalExperienceBundle, SiteDotCom excluded
Cross-cloud deployment checklistPre-flight verification list for API version alignment, SiteDotCom exclusion, and layer sequencing

Package files