STAGING
Concepts

Previews and publishing

Why every change ships through a preview URL before production.

The single most opinionated thing about Showly: production receives nothing that has not already been a preview. This page explains why, and what that means in practice.

What a preview is

A preview is an immutable build artifact plus a routable URL. It carries:

  • the commit SHA the patch was applied to
  • the diff against the live production artifact
  • the build log
  • check results (lints, type-check, custom CI hooks)
  • the agent or human who produced it

Authenticated workspace Previews live in an isolated namespace. They are crawler-blocked (X-Robots-Tag: noindex), never expire, and never share secrets with production. An unclaimed no-account public trial is a separate flow and still expires after about an hour unless it is claimed.

How a preview is triggered

There are three ways a build is produced:

  • Your agent (Claude Code / Codex over MCP) calls create_preview after staging a change.
  • You build from connected GitHub. Web and MCP can resolve the connected branch and create a password-protected private Preview; Pro+ workspaces can choose workspace-member access instead. Push auto-deploy is off by default and, when explicitly enabled, creates only a private workspace-member Preview—never a Live release. Unattended auto-deploy currently requires Pro+ and a static build target; unsupported runtime targets are skipped with an in-app notification. (Source is cloned with a short-lived, scoped GitHub App token that never enters the build environment.)
  • A retry/rebuild. A failed or canceled deployment can be rebuilt — from the dashboard's Rebuild button or the retry_deployment MCP tool. Showly retains the source bundle, so a rebuild is one click with no re-upload.

Every path lands on the same artifact + preview URL. Preview builds are free. A successful production deployment consumes 15 credits; failed production deployments do not. If a build fails, the deployment carries the failure stage, error code, message, and a build-log tail so you can see why before retrying.

For password access, Showly generates a short XXX-XXX sharing code with ambiguous characters removed. You can instead choose any 6–128 character password. The plaintext is shown only when the Preview is created or its password is rotated; use Copy URL + password to copy a ready-to-forward credential block. Existing passwords remain valid until you rotate them. For sensitive internal reviews, prefer Pro organization access or choose a longer password.

What a publish is

A publish is the promotion of an _existing preview artifact_ to the production route. Showly does not rebuild on publish. The artifact you approved is the artifact that ships. This is what makes rollback safe: rollback is "swap the route pointer back," not "rerun the build."

Preview and Live are separate addresses. The Preview remains private and never turns into a public URL; publishing creates a production deployment for the site's Live address. The source Preview remains available for review until it is explicitly deleted, with no plan-based expiration.

What approval is

Approval is a recorded decision by a workspace member who is allowed to approve the publish. The roles are owner, admin, developer, deployer, and viewer; a publish request created over MCP requires one approval from an owner or admin. The decision is durable: even if the approver leaves the workspace tomorrow, the audit record names them as the approver of revision N. A requester cannot approve their own request, and a rejection is final.

Approval workflows are controlled by the approvalWorkflows entitlement. When it is disabled, the requester publishes with an explicit browser action or the agent's two-step publish_site confirmation. OTP/MFA enrollment is not required, and the waived approval gate is recorded in the audit log.

What rollback is

The Rollback button in the editor swaps the live route pointer to a prior artifact. Rollback remains a separate high-risk action with its own confirmation controls. The rolled-back-from artifact is _kept_ — you can re-promote it later if the rollback turns out to have been the wrong call.

Why the publish loop matters

A typical Showly publish goes:

  1. Agent calls create_change_plan → human reviews the plan.
  2. Agent calls apply_site_patch + create_preview → preview URL generated.
  3. Human visits preview, runs through critical flows.
  4. Optional: run_checks runs the workspace's custom check matrix.
  5. Agent calls request_publish → a pending approval is created. The tool returns an approval envelope (see below) with a webApprovalUrl deep link.
  6. A workspace member opens the webApprovalUrl and approves (or denies) the request.
  7. A human clicks Publish in the web UI; no OTP setup is required. The publish promotes the approved preview deployment to production and carries sourceDeploymentId set to that preview deployment's id.

request_publish returns an approval envelope:

{
  "approvalId": "apr_...",
  "deploymentId": "dep_...",
  "state": "pending",
  "expiresAt": "2026-05-31T10:00:00.000Z",
  "reused": false,
  "webApprovalUrl": "https://showly.ai/app/deployments/dep_.../publish"
}

state is one of pending, approved, denied, or expired, and reused is true when an existing pending approval for the same deployment is returned instead of a new one. publish_site is also available through MCP as a two-step, deployment-bound human confirmation flow.

Each step is auditable; each step has an obvious failure mode that doesn't reach production.

What about hotfixes?

Hotfixes still go through a private Preview first. There is no emergency bypass: publishing still needs a ready Preview, the explicit publish confirmation, and any workspace-required approval, but not OTP enrollment.