Experience Cloud Deployment Admin
This skill activates when a practitioner needs to deploy an Experience Cloud site from one Salesforce org to another using change sets, the Salesforce CLI, or the Metadata API. It enforces the strict metadata ordering rules required by ExperienceBundle and guides the admin through the manual publish step that must follow every deployment.
Before Starting
Gather this context before working on anything in this domain:
- Confirm that Enable Experience Bundle Metadata API is checked in Setup > Digital Experiences > Settings in both the source org and the target org. Without this flag, ExperienceBundle metadata cannot be retrieved or deployed.
- Identify the full dependency chain: Apex classes used by the site, custom objects, profiles, permission sets, and any connected apps must be deployed before the site metadata.
- The most common wrong assumption is that deploying ExperienceBundle alone is sufficient. The Network, CustomSite, and all Apex/class dependencies must already exist in the target org before the ExperienceBundle deploy step.
- A successful deployment does not automatically publish the site. A site that has never been published stays at
Network.Status = UnderConstruction (Setup label Preview) until an admin triggers Publish in Experience Builder or calls the Connect REST API.
Core Concepts
ExperienceBundle Metadata Type
ExperienceBundle is the primary metadata type representing an Experience Cloud site built in Experience Builder (LWR or Aura-based). It stores page layouts, themes, component configurations, and navigation menus as JSON and XML files. It does not store the classic SiteDotCom blob — including the SiteDotCom component in the same deployment package as ExperienceBundle causes the entire deployment to fail, even if all other metadata is valid.
ExperienceBundle is only available for retrieval and deployment when the Enable Experience Bundle Metadata API checkbox is active in both the source and the target org. This setting does not transfer automatically during provisioning.
Network and CustomSite — Required Predecessors
The Network metadata type represents the configuration record for the Experience Cloud site (domain, status, authentication settings). The CustomSite metadata type represents the underlying site record that controls URL mappings and guest user access. Both must already exist in the target org before ExperienceBundle can be deployed successfully. Deploying ExperienceBundle into a target org that has no matching Network record will fail with a cryptic metadata error rather than a clear dependency message.
Deployment Ordering Rule
The required metadata deployment order for an Experience Cloud site is:
- Apex classes, Apex triggers, and Lightning components that the site references
- Custom objects, custom fields, and record types that site pages surface
- Profiles and permission sets (including the site Guest User Profile)
Network and CustomSite metadataExperienceBundle
Violating this sequence — for example, deploying ExperienceBundle and Network in the same change set in the wrong order — causes deployment failures that are difficult to diagnose because the Salesforce error messages reference the ExperienceBundle rather than the missing dependency.
Unpublished Status After Deployment
A successful ExperienceBundle deployment never publishes, regardless of the status the site had in the source org. Network.Status is a restricted picklist whose API values differ from the Setup labels — UnderConstruction is labelled Preview and Live is labelled Published — so a site that has never been published sits at UnderConstruction, not at a status named "Draft" or "Active". A target site that was already published stays at Live (UnderConstruction is one-way — a published site can never return to it) and keeps serving its last published version. In both cases the deployed content reaches members only after a workspace admin explicitly triggers Publish in Experience Builder (Preview > Publish) or programmatically publishes it via the Connect REST API (POST /connect/communities/{communityId}/publish). This is a platform-enforced safety gate, not a bug.
Common Patterns
Pattern: Staged Change Set Deployment
When to use: An admin-managed org with no SFDX or CLI tooling, deploying a new or updated Experience Cloud site from sandbox to production using change sets.
How it works:
- Outbound change set in the source org includes: all Apex classes/triggers, custom objects/fields, profiles,
Network, CustomSite, and ExperienceBundle for the site.
- Upload and then deploy the change set containing Apex and data model components first — validate and deploy without ExperienceBundle.
- Deploy a second change set containing
Network, CustomSite, and ExperienceBundle in sequence.
- After deployment completes, log in to the target org, open Experience Builder for the site, and click Publish.
Why not a single change set: Change sets deploy all components simultaneously and do not guarantee a dependency-aware ordering within the set. When ExperienceBundle and Network land together, ExperienceBundle may attempt to resolve references before Network is committed, causing the deploy to fail.
Pattern: SFDX CLI Sequenced Deploy
When to use: Source-tracked project using Salesforce CLI (sf or sfdx) with a manifest (package.xml) targeting a sandbox or scratch org.
How it works:
- Split the manifest into two:
package-deps.xml (Apex, objects, profiles, Network, CustomSite) and package-site.xml (ExperienceBundle only).
- Run:
sf project deploy start --manifest package-deps.xml --target-org <alias> and wait for success.
- Run:
sf project deploy start --manifest package-site.xml --target-org <alias>.
- Publish via Connect REST API or Experience Builder UI.
Why not the alternative: Deploying a single merged package.xml containing both Network and ExperienceBundle risks the same ordering failure as unordered change sets.
Decision Guidance
| Situation |
Recommended Approach |
Reason |
| First-time site deploy; Network does not exist in target |
Deploy Network + CustomSite before ExperienceBundle |
ExperienceBundle requires an existing Network record in target |
| Site already exists in target, updating component configs only |
Deploy ExperienceBundle alone after verifying Network is present |
Reduces deployment surface and risk |
| Site uses Apex controllers or custom LWC |
Deploy Apex/LWC first in a separate step before deploying Network and ExperienceBundle |
Avoids reference resolution failures in ExperienceBundle |
| Need automated publish after CLI deploy |
Use Connect REST API POST /connect/communities/{communityId}/publish |
Removes manual step from the release pipeline |
| SiteDotCom blob present in retrieval output |
Remove SiteDotCom from the deployment package before deploying |
Including SiteDotCom with ExperienceBundle causes deploy failure |
| Enable Experience Bundle Metadata API not active in target |
Enable in Setup > Digital Experiences > Settings before deploying |
ExperienceBundle cannot be deployed without this flag |
Recommended Workflow
Step-by-step instructions for an AI agent or practitioner working on this task:
- Verify Experience Bundle Metadata API is enabled in both source and target orgs. Navigate to Setup > Digital Experiences > Settings and confirm the checkbox. Without this, retrieval and deployment of ExperienceBundle will fail silently or with misleading errors.
- Retrieve the full site metadata from the source org including
Network, CustomSite, and ExperienceBundle. Review the retrieved package and remove any SiteDotCom component — it must not be included in the deployment package.
- Identify and stage all Apex, LWC, and data model dependencies the site references (Apex classes, triggers, custom objects, custom fields, record types, profiles, permission sets). Deploy these to the target org first and confirm success before proceeding.
- Deploy Network and CustomSite to the target org. Confirm that the Network record now exists in the target (visible in Setup > All Sites).
- Deploy ExperienceBundle in a separate deployment step after Network and CustomSite are confirmed present. Monitor deployment status and address any component-level errors before retrying.
- Publish the site in the target org. Either open Experience Builder > Publish, or call
POST /connect/communities/{communityId}/publish via the Connect REST API. Confirm Network.Status is now Live (Setup shows the label Published) and the URL is reachable.
- Validate guest user access and profile permissions in the target org. The Guest User Profile for the site does not automatically inherit permission changes from the source — verify Apex class access, object CRUD permissions, and field-level security match the source configuration.
Review Checklist
Run through these before marking work in this area complete:
Salesforce-Specific Gotchas
Non-obvious platform behaviors that cause real production problems:
- SiteDotCom blob breaks ExperienceBundle deployment — When retrieving an Experience Cloud site, Salesforce includes a
SiteDotCom component in the retrieved package. If this component is included when deploying ExperienceBundle, the entire deployment fails, often with a misleading error. Always strip SiteDotCom from the deployment manifest before deploying.
- Deployment does not publish the site — A successful ExperienceBundle deployment never publishes: a never-published site stays at
Network.Status = UnderConstruction (Setup label Preview), and an already-published site stays at Live but keeps serving its last published version. End users do not see the deployed site or the deployed changes until an admin publishes. Teams frequently discover this only after release to production when users report the site is inaccessible.
- Enable Experience Bundle Metadata API must be set in both orgs independently — This setting is org-specific and does not replicate via sandbox refresh or org copy. Every new sandbox or scratch org requires this checkbox to be enabled before ExperienceBundle can be retrieved or deployed.
- Network record name must match exactly — The
Network metadata component is keyed by the site name. If the site was renamed in the source org, the target org must also have a Network record with the exact same name, or the ExperienceBundle deploy will fail to find its parent Network.
- Guest User Profile changes require a separate profile deployment — Changes made to the site's Guest User Profile (Apex class access, object permissions) are not included in ExperienceBundle. They must be retrieved and deployed separately as a
Profile metadata component, otherwise the target site may behave differently from the source.
Output Artifacts
| Artifact |
Description |
| Ordered deployment plan |
A sequenced list of change sets or CLI commands covering Apex/LWC deps → Network/CustomSite → ExperienceBundle |
| Pre-deployment checklist |
Verification steps for Experience Bundle Metadata API flag, SiteDotCom removal, and dependency readiness |
| Post-deployment publishing runbook |
Step-by-step instructions for publishing the site via UI or Connect REST API |
| Guest User Profile review notes |
Summary of permissions that must be manually validated in the target org after deployment |
Related Skills
- devops/change-set-deployment — Use for the general change set deployment workflow when the Experience Cloud site is one component among many in a broader release.
- devops/pre-deployment-checklist — Use to build the full org-level pre-deployment checklist; this skill provides the Experience Cloud-specific items to add.
- devops/deployment-monitoring — Use to monitor deployment status and interpret deployment errors after initiating the ExperienceBundle deploy step.
- lwc/experience-cloud-lwc-components — Use when the site references custom LWC components that must be authored or updated before deployment.
1---2name: experience-cloud-deployment-admin3description: Deploying an Experience Cloud site (formerly Community) between Salesforce orgs or sandboxes: metadata ordering, ExperienceBundle enablement, post-deployment publishing, change-set or SFDX-based migration. NOT for automating the deploy in a CI/CD pipeline, or LWR DigitalExperienceBundle — use devops/experience-cloud-deployment-dev. NOT for building the site in Experience Builder — use admin/experience-cloud-site-setup.4---56# Experience Cloud Deployment Admin78This skill activates when a practitioner needs to deploy an Experience Cloud site from one Salesforce org to another using change sets, the Salesforce CLI, or the Metadata API. It enforces the strict metadata ordering rules required by ExperienceBundle and guides the admin through the manual publish step that must follow every deployment.910---1112## Before Starting1314Gather this context before working on anything in this domain:1516- Confirm that **Enable Experience Bundle Metadata API** is checked in Setup > Digital Experiences > Settings in both the source org and the target org. Without this flag, ExperienceBundle metadata cannot be retrieved or deployed.17- Identify the full dependency chain: Apex classes used by the site, custom objects, profiles, permission sets, and any connected apps must be deployed before the site metadata.18- The most common wrong assumption is that deploying ExperienceBundle alone is sufficient. The Network, CustomSite, and all Apex/class dependencies must already exist in the target org before the ExperienceBundle deploy step.19- A successful deployment does not automatically publish the site. A site that has never been published stays at `Network.Status = UnderConstruction` (Setup label **Preview**) until an admin triggers Publish in Experience Builder or calls the Connect REST API.2021---2223## Core Concepts2425### ExperienceBundle Metadata Type2627ExperienceBundle is the primary metadata type representing an Experience Cloud site built in Experience Builder (LWR or Aura-based). It stores page layouts, themes, component configurations, and navigation menus as JSON and XML files. It does not store the classic SiteDotCom blob — including the SiteDotCom component in the same deployment package as ExperienceBundle causes the entire deployment to fail, even if all other metadata is valid.2829ExperienceBundle is only available for retrieval and deployment when the **Enable Experience Bundle Metadata API** checkbox is active in both the source and the target org. This setting does not transfer automatically during provisioning.3031### Network and CustomSite — Required Predecessors3233The `Network` metadata type represents the configuration record for the Experience Cloud site (domain, status, authentication settings). The `CustomSite` metadata type represents the underlying site record that controls URL mappings and guest user access. Both must already exist in the target org before ExperienceBundle can be deployed successfully. Deploying ExperienceBundle into a target org that has no matching Network record will fail with a cryptic metadata error rather than a clear dependency message.3435### Deployment Ordering Rule3637The required metadata deployment order for an Experience Cloud site is:38391. Apex classes, Apex triggers, and Lightning components that the site references402. Custom objects, custom fields, and record types that site pages surface413. Profiles and permission sets (including the site Guest User Profile)424. `Network` and `CustomSite` metadata435. `ExperienceBundle`4445Violating this sequence — for example, deploying ExperienceBundle and Network in the same change set in the wrong order — causes deployment failures that are difficult to diagnose because the Salesforce error messages reference the ExperienceBundle rather than the missing dependency.4647### Unpublished Status After Deployment4849A successful ExperienceBundle deployment never publishes, regardless of the status the site had in the source org. `Network.Status` is a restricted picklist whose API values differ from the Setup labels — `UnderConstruction` is labelled **Preview** and `Live` is labelled **Published** — so a site that has never been published sits at `UnderConstruction`, not at a status named "Draft" or "Active". A target site that was already published stays at `Live` (`UnderConstruction` is one-way — a published site can never return to it) and keeps serving its last published version. In both cases the deployed content reaches members only after a workspace admin explicitly triggers Publish in Experience Builder (Preview > Publish) or programmatically publishes it via the Connect REST API (`POST /connect/communities/{communityId}/publish`). This is a platform-enforced safety gate, not a bug.5051---5253## Common Patterns5455### Pattern: Staged Change Set Deployment5657**When to use:** An admin-managed org with no SFDX or CLI tooling, deploying a new or updated Experience Cloud site from sandbox to production using change sets.5859**How it works:**601. Outbound change set in the source org includes: all Apex classes/triggers, custom objects/fields, profiles, `Network`, `CustomSite`, and `ExperienceBundle` for the site.612. Upload and then deploy the change set containing Apex and data model components first — validate and deploy without ExperienceBundle.623. Deploy a second change set containing `Network`, `CustomSite`, and `ExperienceBundle` in sequence.634. After deployment completes, log in to the target org, open Experience Builder for the site, and click Publish.6465**Why not a single change set:** Change sets deploy all components simultaneously and do not guarantee a dependency-aware ordering within the set. When ExperienceBundle and Network land together, ExperienceBundle may attempt to resolve references before Network is committed, causing the deploy to fail.6667### Pattern: SFDX CLI Sequenced Deploy6869**When to use:** Source-tracked project using Salesforce CLI (`sf` or `sfdx`) with a manifest (`package.xml`) targeting a sandbox or scratch org.7071**How it works:**721. Split the manifest into two: `package-deps.xml` (Apex, objects, profiles, Network, CustomSite) and `package-site.xml` (ExperienceBundle only).732. Run: `sf project deploy start --manifest package-deps.xml --target-org <alias>` and wait for success.743. Run: `sf project deploy start --manifest package-site.xml --target-org <alias>`.754. Publish via Connect REST API or Experience Builder UI.7677**Why not the alternative:** Deploying a single merged `package.xml` containing both Network and ExperienceBundle risks the same ordering failure as unordered change sets.7879---8081## Decision Guidance8283| Situation | Recommended Approach | Reason |84|---|---|---|85| First-time site deploy; Network does not exist in target | Deploy Network + CustomSite before ExperienceBundle | ExperienceBundle requires an existing Network record in target |86| Site already exists in target, updating component configs only | Deploy ExperienceBundle alone after verifying Network is present | Reduces deployment surface and risk |87| Site uses Apex controllers or custom LWC | Deploy Apex/LWC first in a separate step before deploying Network and ExperienceBundle | Avoids reference resolution failures in ExperienceBundle |88| Need automated publish after CLI deploy | Use Connect REST API `POST /connect/communities/{communityId}/publish` | Removes manual step from the release pipeline |89| SiteDotCom blob present in retrieval output | Remove SiteDotCom from the deployment package before deploying | Including SiteDotCom with ExperienceBundle causes deploy failure |90| Enable Experience Bundle Metadata API not active in target | Enable in Setup > Digital Experiences > Settings before deploying | ExperienceBundle cannot be deployed without this flag |9192---9394## Recommended Workflow9596Step-by-step instructions for an AI agent or practitioner working on this task:97981. **Verify Experience Bundle Metadata API is enabled** in both source and target orgs. Navigate to Setup > Digital Experiences > Settings and confirm the checkbox. Without this, retrieval and deployment of ExperienceBundle will fail silently or with misleading errors.992. **Retrieve the full site metadata** from the source org including `Network`, `CustomSite`, and `ExperienceBundle`. Review the retrieved package and remove any `SiteDotCom` component — it must not be included in the deployment package.1003. **Identify and stage all Apex, LWC, and data model dependencies** the site references (Apex classes, triggers, custom objects, custom fields, record types, profiles, permission sets). Deploy these to the target org first and confirm success before proceeding.1014. **Deploy Network and CustomSite** to the target org. Confirm that the Network record now exists in the target (visible in Setup > All Sites).1025. **Deploy ExperienceBundle** in a separate deployment step after Network and CustomSite are confirmed present. Monitor deployment status and address any component-level errors before retrying.1036. **Publish the site** in the target org. Either open Experience Builder > Publish, or call `POST /connect/communities/{communityId}/publish` via the Connect REST API. Confirm `Network.Status` is now `Live` (Setup shows the label **Published**) and the URL is reachable.1047. **Validate guest user access and profile permissions** in the target org. The Guest User Profile for the site does not automatically inherit permission changes from the source — verify Apex class access, object CRUD permissions, and field-level security match the source configuration.105106---107108## Review Checklist109110Run through these before marking work in this area complete:111112- [ ] Enable Experience Bundle Metadata API is active in the target org113- [ ] SiteDotCom component is absent from the deployment package114- [ ] All Apex classes and LWC dependencies are deployed and accessible in the target before ExperienceBundle deploy115- [ ] Network and CustomSite records exist in the target org before ExperienceBundle is deployed116- [ ] Deployment completed without errors (checked in Setup > Deployment Status)117- [ ] Site is published — `Network.Status = Live`, Setup label **Published** — and reachable at its expected URL in the target org118- [ ] Guest User Profile permissions reviewed and confirmed correct in the target org119120---121122## Salesforce-Specific Gotchas123124Non-obvious platform behaviors that cause real production problems:1251261. **SiteDotCom blob breaks ExperienceBundle deployment** — When retrieving an Experience Cloud site, Salesforce includes a `SiteDotCom` component in the retrieved package. If this component is included when deploying ExperienceBundle, the entire deployment fails, often with a misleading error. Always strip SiteDotCom from the deployment manifest before deploying.1272. **Deployment does not publish the site** — A successful ExperienceBundle deployment never publishes: a never-published site stays at `Network.Status = UnderConstruction` (Setup label Preview), and an already-published site stays at `Live` but keeps serving its last published version. End users do not see the deployed site or the deployed changes until an admin publishes. Teams frequently discover this only after release to production when users report the site is inaccessible.1283. **Enable Experience Bundle Metadata API must be set in both orgs independently** — This setting is org-specific and does not replicate via sandbox refresh or org copy. Every new sandbox or scratch org requires this checkbox to be enabled before ExperienceBundle can be retrieved or deployed.1294. **Network record name must match exactly** — The `Network` metadata component is keyed by the site name. If the site was renamed in the source org, the target org must also have a Network record with the exact same name, or the ExperienceBundle deploy will fail to find its parent Network.1305. **Guest User Profile changes require a separate profile deployment** — Changes made to the site's Guest User Profile (Apex class access, object permissions) are not included in ExperienceBundle. They must be retrieved and deployed separately as a `Profile` metadata component, otherwise the target site may behave differently from the source.131132---133134## Output Artifacts135136| Artifact | Description |137|---|---|138| Ordered deployment plan | A sequenced list of change sets or CLI commands covering Apex/LWC deps → Network/CustomSite → ExperienceBundle |139| Pre-deployment checklist | Verification steps for Experience Bundle Metadata API flag, SiteDotCom removal, and dependency readiness |140| Post-deployment publishing runbook | Step-by-step instructions for publishing the site via UI or Connect REST API |141| Guest User Profile review notes | Summary of permissions that must be manually validated in the target org after deployment |142143---144145## Related Skills146147- **devops/change-set-deployment** — Use for the general change set deployment workflow when the Experience Cloud site is one component among many in a broader release.148- **devops/pre-deployment-checklist** — Use to build the full org-level pre-deployment checklist; this skill provides the Experience Cloud-specific items to add.149- **devops/deployment-monitoring** — Use to monitor deployment status and interpret deployment errors after initiating the ExperienceBundle deploy step.150- **lwc/experience-cloud-lwc-components** — Use when the site references custom LWC components that must be authored or updated before deployment.
PranavNagrecha