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 push to GitHub. When a site is connected to a GitHub repo, a push to that site's deploy branch automatically builds a new preview — no manual step. Pushes to other branches are ignored. Auto-deploy is on by default for GitHub-connected sites and can be turned off per site. (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.

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."

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.

What rollback is

The Rollback button in the editor swaps the live route pointer to a prior artifact. (Rollback is not exposed as an MCP tool — like production publish, it requires step-up MFA in the web UI.) 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 with fresh step-up MFA publishes from the web UI. The publish promotes the approved preview deployment to production; the production deploy carries sourceDeploymentId set to that approved preview deployment's id (the field is pre-filled by the UI).

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. Production publish itself (publish_site) is not an MCP tool — it runs only in the web UI behind step-up MFA plus approval.

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

What about hotfixes?

Hotfixes still go through preview first. The current production path does not expose an MCP emergency bypass; a human can accelerate review, but the publish still needs a ready preview, approval, and fresh MFA.