Review and publish a CMS site

Move a CMS site from source to live delivery in separate steps. Green developer readiness confirms that authoring and preview work. It does not mean that a release has already been built or published.

If needed, configure the local host first with Set up a local storefront domain. This quickstart is complete when the live domain serves the deliberately published release and operations readiness reports no blockers.

Distinguish the states

StateMeaningNext step
No buildThe site can be edited and previewed, but no release exists yet.Review the preview and start a build.
Build runningWorkspace is creating an immutable release.Wait for completion.
Build failedThe release was not created reliably. The status provides a redacted error code, retryable, and an attempt ID.Check the recovery class; never rebuild or publish automatically.
Release unpublishedA build exists but is not live.Review the release and publish it deliberately.
Release publishedThe selected release is live.Check the live domain and operations readiness.
Live release incompleteThe active release has no complete runtime catalog, so Workspace blocks the entire release with HTTP 503.Select an existing runtime-ready release or build a new one, review it, and publish it deliberately.

When site-domain binding, DNS, and TLS are ready, Workspace returns an expected HTTP 404 instead of live content before the first publication. Treat 404 as a missing live release only in this case. This also applies directly after initialization and after a successful build without publication. Blocked domain, DNS, TLS, or binding checks remain separate blockers. A damaged or unreadable live state still returns HTTP 503 and does not count as unpublished.

Move from preview to live

  1. Open CMS > Sites and select the site.
  2. Initialize an empty site once with the default kit.
  3. Start a dev session and edit files on the Editor tab.
  4. Generate a preview link and review the result.
  5. Open the Releases tab and start the build.
  6. Wait until the new release appears in the list.
  7. Review the release and the publish plan for that exact version. Resolve remaining blockers before publication.
  8. Explicitly confirm Publish for that release.
  9. Check the live domain, access to protected pages, and operations readiness.

A build never publishes automatically. A successful new build also leaves an existing live release unchanged until you publish explicitly.

Verify tenant-protected pages

For tenant-protected CMS pages, the browser session's active tenant must match the Site's tenant. Configured page permissions and optional audience groups then determine access. Membership in multiple tenants does not replace the matching active context.

Before publication, test an anonymous request, an authorized member, and an identity that belongs only to another tenant. An anonymous request must not receive protected page content. A signed-in identity with the wrong active tenant receives HTTP 403. Test these cases in preview and again after publication. A preview link does not replace page permissions. If the Site uses its own login page, that page must be public; configure a login redirect only for missing authentication (HTTP 401) so HTTP 403 does not cause a login loop.

Handle build failures safely

Keep the attemptId returned by the build request. nucli sites build <site-id> --wait accepts only a status for that attempt. When escalating, provide the attempt ID, failure.code, and failure.retryable, but do not include internal logs, file paths, or raw errors.

Failure codesMeaningRecovery
SITE_BUILD_AUTHORING_REFRESH_FAILED, SITE_BUILD_REDIRECTS_FAILED, SITE_BUILD_ASSETS_FAILED, SITE_BUILD_RENDER_FAILED, SITE_BUILD_PUBLIC_FILES_FAILED, SITE_BUILD_ROUTING_FAILED, SITE_BUILD_DYNAMIC_ROUTES_FAILED, SITE_BUILD_SITEMAP_FAILED, SITE_BUILD_SEARCH_MANIFEST_FAILED, SITE_BUILD_IMAGES_FAILEDAn authoring-dependent build stage could not process the validated sources.Revalidate the affected sources, then deliberately start a new build.
SITE_BUILD_CAPACITY_UNAVAILABLE, SITE_BUILD_STORAGE_PREPARE_FAILED, SITE_BUILD_SOURCE_SNAPSHOT_FAILED, SITE_BUILD_STAGING_FAILED, SITE_BUILD_RELEASE_FINALIZE_FAILEDAn external build prerequisite was unavailable. These codes are marked retryable.Have operations restore the documented capacity, storage, snapshot, staging, or release prerequisite. Only then deliberately start a new build.
SITE_BUILD_RUNTIME_SNAPSHOT_FAILED, SITE_BUILD_RUNTIME_CATALOG_FAILED, SITE_BUILD_PRECOMPRESSION_FAILED, SITE_BUILD_PUBLISH_FAILED, SITE_BUILD_INTERNALThe failure requires product diagnostics or has no safe public recovery.Escalate to the product team with the attempt ID. Do not retry or publish automatically.

retryable: true means only that another attempt may make sense after the external prerequisite has demonstrably recovered. A failed build leaves the current live release unchanged.

Navigation, page resolution, and the page feed belong to the immutable release. Editor changes therefore appear only in development and preview. They reach the live site only after a new build and an explicit publication.

Publish after a product update

Have operations complete the product update and required server restart before checking publication state again. A product update never publishes a site release automatically.

An older live release without a complete runtime catalog may be blocked with HTTP 503 and ERR_SITE_RELEASE_RUNTIME_UNAVAILABLE. This is not a normal page error and does not require reverting authoring files.

  1. Review the available releases. Reuse an existing target that has been built, reviewed, and found runtime-ready. Build a new release if none is suitable.
  2. Check the publish plan for that exact target. The release_runtime_ready check must be ready. Have operations investigate remaining infrastructure, binding, or read failures.
  3. Explicitly publish the selected release.
  4. Verify live content, access to protected pages, and operations readiness.

Publishing rejects an incomplete target without switching the active live release. A state check never repairs or publishes anything and does not require rebuilding an already valid release as a precaution.

The preview link expires with the selected review window. It is redeemed once in the intended browser and establishes preview access there. Do not test-open the link or call it automatically, because that consumes the handoff.

Never store concrete preview tokens in logs, tickets, screenshots, or documentation. Generate or copy a link only for the intended reviewer. A preview link does not publish the site.

Verify with nucli

bash
nucli --tenant <tenant> sites readiness <site-id>
nucli --tenant <tenant> web readiness <site-id>
nucli --tenant <tenant> sites build <site-id> --wait
nucli --tenant <tenant> sites build-status <site-id>
nucli --tenant <tenant> sites releases list <site-id>
nucli --tenant <tenant> sites inspect <site-id> --strict
nucli --tenant <tenant> sites publish plan <site-id> --release <release-id>
nucli --tenant <tenant> sites publish <site-id> --release <release-id>

sites readiness evaluates authoring and preview. Use inspect --strict only as a launch gate. web readiness evaluates domain, DNS, TLS, build, and live release. The publish plan is read-only: it may accept an unpublished release and a transition away from a blocked old live release when the selected target is runtime-ready. If the old release returns HTTP 503, this exception applies only when Workspace itself detects a runtime failure in the bound release and verifies proof that binds the response to the request, domain, site, and active site release in the current workspace. Diagnostic headers or HTTP 503 alone are insufficient. Other HTTP errors and infrastructure, release-read, or build failures remain blocking.

Approve mutating MCP calls

When an MCP agent performs this workflow, exactly these 13 Site and domain tools require the JSON Boolean approved: true in the same call:

  • nucleus_site_files_apply
  • nucleus_site_backup_save
  • nucleus_site_restore_apply
  • nucleus_site_dev_start
  • nucleus_site_preview_link_request
  • nucleus_site_dependencies_add
  • nucleus_site_dependencies_sync
  • nucleus_site_build
  • nucleus_site_publish
  • nucleus_tenant_domain_create
  • nucleus_tenant_domain_start_verification
  • nucleus_tenant_domain_verify_dns
  • nucleus_site_domain_bind

Approve only the concrete tool call and its complete payload. If approved is missing, false, null, or not a Boolean, nucli stops before file, secret, network, or server access. The field remains local and does not replace authentication, permissions, tenant binding, or Workspace validation. Read-only tools and the side-effect-free nucleus_site_validate and nucleus_site_restore_preview tools remain unchanged.

Prepare error pages

Use access.surface: public for custom error pages named 401, 403, 404, and 500, including paths such as en/404 or help/404. Protected error pages are rejected during builds. Existing source files remain loadable at server startup with their access rules intact. Include only content that may be viewed without signing in.

For existing releases, a generic error page replaces a protected custom page or one whose public access rule is missing from the release. The rest of the site remains available. Correct the error page and publish a new build to restore its custom presentation.

Exclude protected pages from sitemaps

New builds include only pages with valid access.surface: public and sitemap: true in public sitemaps. Setting sitemap: true on a protected page does not expose its URL. Publish a new build to replace existing sitemap files.

Working on concurrent changes

When saving, Workspace checks that the loaded file version is still current. If someone has changed the same file, you receive a version conflict and your draft stays in the editor. Compare it with the current file and reconcile the changes before saving again. Changes to other files do not cause this conflict.

Edits made while a save request is running stay marked as unsaved. The save acknowledgement applies to the content sent in that request. New source operations use the current generation; operations already in progress finish using their selected generation. The public website continues to use the last explicitly published release.

When changes cannot be saved

Workspace reports ERR_SITE_SOURCE_GENERATION_LIMIT when source capacity is exhausted. The editor keeps the unsaved draft. Inspect the correct tenant:

bash
nucli --tenant <tenant> sites sources status <site-id> --json
nucli --tenant <tenant> sites sources cleanup <site-id> --json

Status requires Site read permission; cleanup requires Site workspace management permission. Cleanup previews a plan by default. Add --apply to request collection on the running server. Collection requires an approved reader protocol and remains blocked when protocolState is bridge. Active readers retain their source files until their work finishes. trashGenerationCount reports detached generations awaiting physical deletion. Source cleanup does not publish a release.

ERR_SITE_SOURCE_RETENTION_UNAVAILABLE means that safe source access is currently unavailable. ERR_SITE_SOURCE_STORAGE_EXHAUSTED means that disk space or a storage quota is exhausted. Ask an administrator to investigate. Verify recovery through status and a successfully saved draft.

Verify the result

Publication is complete when web readiness reports no blockers, the selected release is marked live, and the live domain serves the reviewed content instead of the expected pre-publication 404.