Skip to main content
Live with caveats. This area is real and usable, but the docs intentionally call out operational or UX limits that still matter.

​
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

1
Push an exact commit to the configured development branch or primary branch.
2
StackShift builds and deploys the corresponding isolated backend.
3
A leased release worker checks out that exact commit, performs a frozen install, validates config, builds app components, and publishes a deterministic Shopify version.
4
Watch release status, step, attempt count, redacted logs, and launch checks on the Shopify project page.
5
Retry only a failed or degraded release after correcting its cause; use the normal deployment rollback action for a coupled rollback.

​
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.
  • 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

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

​
Common failures

  • 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

Configure Shopify app hosting

Prepare supported app source, separate Shopify app targets, committed TOML files, credentials, managed databases, and verification.

Shopify webhooks and observability

Application-owned HMAC verification, metadata-only ingress observations, duplicate accounting, retention, alerts, and launch checks.

Shopify security and troubleshooting

Credential storage and isolation guarantees, launch-check interpretation, stable failure codes, and a production diagnosis sequence.