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

# Shopify app releases and rollbacks

> How backend deployments are coupled to deterministic Shopify configuration and extension releases, retries, and compensation.

<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

Understand exactly when a Shopify app release runs, what it publishes, and how StackShift prevents backend and Shopify versions from drifting.

## Prerequisites

* Both app environments verified
* App release automation enabled by the platform operator
* A healthy build from the primary or configured development branch

## Workflow

<Steps>
  <Step>
    Push an exact commit to the configured development branch or primary branch.
  </Step>

  <Step>
    StackShift builds and deploys the corresponding isolated backend.
  </Step>

  <Step>
    A leased release worker checks out that exact commit, performs a frozen install, validates config, builds app components, and publishes a deterministic Shopify version.
  </Step>

  <Step>
    Watch release status, step, attempt count, redacted logs, and launch checks on the Shopify project page.
  </Step>

  <Step>
    Retry only a failed or degraded release after correcting its cause; use the normal deployment rollback action for a coupled rollback.
  </Step>
</Steps>

## Release identity and ordering

* Normal app versions use `stackshift-<build UUID without hyphens>`.
* Only one queued or running release is allowed for a connection/environment.
* Production releases follow healthy primary-branch deployments. Development releases follow successful builds on the configured development branch and deploy an isolated development runtime first.
* The source checkout is detached at the recorded commit. npm uses `npm ci`; pnpm and Yarn use the exact `packageManager` version and frozen-lockfile mode.

## CLI safety contract

The automated update-only policy follows Shopify’s current guidance to use `--allow-updates` without `--allow-deletes` for unattended pipelines. See Shopify’s [CLI release-safety change](https://shopify.dev/changelog/the-shopify-cli-app-release-force-flag-is-deprecated-and-will-be-removed).

* StackShift runs `app config validate` and `app build` before exposing the automation token to the process environment.
* Deployment uses `app deploy --no-build --allow-updates`; it does not use `--allow-deletes`, so automated releases cannot approve extension deletion.
* Rollback selects a previously recorded exact version with `app release --allow-updates --version`.
* The CLI is exact-pinned. A project-local exact Shopify CLI dependency takes precedence; otherwise the platform pin is used.
* Runner output is capped and redacted for exact known secrets and secret-shaped patterns before persistence.

## Retries and compensation

* A release lease is 30 minutes, processing is bounded to 25 minutes, and the CLI deployment sub-step is bounded to 15 minutes.
* Transient failures retry with bounded minute-scale backoff, up to five attempts.
* If Shopify publication fails after a backend change, StackShift attempts to restore the prior Shopify version and backend deployment.
* If compensation itself fails, the release becomes `degraded` and StackShift opens a critical operations incident. Treat degraded as manual-attention-required, not as a successful release.
* Retry is accepted only for `failed` or `degraded` releases and is rejected while another release is active.

## Expected result

<Check>
  A healthy backend deployment and its Shopify configuration/extensions reference the same commit and deterministic StackShift version.
</Check>

## Common failures

<Warning>
  * No containerd-ready worker agent or release runner configuration
  * Frozen dependency install fails
  * Committed TOML validation fails
  * Expired or wrong app automation token
  * Shopify CLI times out or Shopify rate-limits the operation
  * Backend compensation or Shopify version restoration fails, producing a degraded release
</Warning>

## Related guides

<CardGroup cols={2}>
  <Card title="Configure Shopify app hosting" href="/shopify/app-hosting-setup">
    Prepare supported app source, separate Shopify app targets, committed TOML files, credentials, managed databases, and verification.
  </Card>

  <Card title="Shopify webhooks and observability" href="/shopify/webhooks-and-observability">
    Application-owned HMAC verification, metadata-only ingress observations, duplicate accounting, retention, alerts, and launch checks.
  </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>