> ## Documentation Index
> Fetch the complete documentation index at: https://docs.stackshift.cloud/llms.txt
> Use this file to discover all available pages before exploring further.

# Storefront previews, promotion, and domains

> Test on generated URLs and promote an active preview’s exact immutable image to production without rebuilding it.

<Warning>
  **Live with caveats.** This area is real and usable, but the docs intentionally call out operational or UX limits that still matter.
</Warning>

## Goal

Promote exactly what was reviewed in preview while enforcing production credentials, TLS, health, and expiry gates.

## Prerequisites

* A verified production storefront target
* A running, unexpired preview from a successful build
* A production HTTPS URL

## Workflow

<Steps>
  <Step>
    Open the branch preview on its generated StackShift HTTPS URL and complete application and checkout testing.
  </Step>

  <Step>
    Confirm the preview is still active, running, unexpired, and associated with a successful immutable build.
  </Step>

  <Step>
    Submit its preview ID from the Shopify project promotion control or API.
  </Step>

  <Step>
    StackShift deploys the exact image digest with production credentials and production domains; it does not rebuild source.
  </Step>

  <Step>
    Wait for the promotion release to become healthy before considering the preview live.
  </Step>
</Steps>

## You do not need to buy a domain to test

Development and preview testing work on generated StackShift HTTPS hostnames. The store’s `*.myshopify.com` identity is also already available and is used only for Shopify API calls.

A custom domain is optional. For final promotion, the production URL must be HTTPS. A StackShift-managed hostname satisfies this gate. If the URL uses an external custom hostname, that domain must belong to the project and show verified DNS plus active SSL in StackShift.

## Immutable image gate

* The preview must reference a successful build owned by the same project.
* The build must have an image URI and a valid `sha256:<64 lowercase hex>` digest.
* The preview image must match either the build image or that image pinned to the recorded digest.
* Promotion deploys `<repository>@<digest>` and records a version named `stackshift-preview-<preview UUID without hyphens>`.

## Failure handling

* Only one active storefront promotion is allowed per connection.
* The production credential and TLS gates run before deployment.
* A production deployment record is activated only after the runtime deploy succeeds.
* If promotion fails after replacing a runtime, StackShift attempts to restore the prior active deployment.
* If no prior deployment exists or rollback fails, the release is degraded and requires manual operator attention.

## Expected result

<Check>
  Production runs the exact digest reviewed in preview, under production credentials and HTTPS routing, with a durable promotion release record.
</Check>

## Common failures

<Warning>
  * Preview is stopped, expired, or no longer active
  * Preview build metadata is missing or image references do not match
  * Production target is not verified
  * Production URL is not HTTPS
  * Custom domain DNS or SSL is not active
  * A promotion is already queued or running
</Warning>

## Related guides

<CardGroup cols={2}>
  <Card title="Configure Shopify storefront hosting" href="/shopify/storefront-hosting-setup">
    Connect Hydrogen or a confirmed Node storefront, obtain Storefront API credentials, isolate targets, and verify Shopify access.
  </Card>

  <Card title="Storefront cache, analytics, and Shop Pay" href="/shopify/cache-analytics-and-shop-pay">
    Configure commerce-safe caching, inspect storefront traffic and checkout redirects, and gate optional Shop Pay activation.
  </Card>

  <Card title="Shopify security and troubleshooting" href="/shopify/security-and-troubleshooting">
    Credential storage and isolation guarantees, launch-check interpretation, stable failure codes, and a production diagnosis sequence.
  </Card>
</CardGroup>