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

Previews live in an isolated namespace. They are crawler-blocked (X-Robots-Tag: noindex), TTL'd (default 14 days; configurable per workspace), and never share secrets with production.

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, and every build counts against your monthly deploy quota. 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 or reaches its retention limit.

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 an entitlement (approvalWorkflows), enabled on Team and Enterprise plans. On Free and Pro there is no second-reviewer gate: 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 plan-required approval, but not OTP enrollment.