How Deployments Work
Every deployment follows the same pipeline, whether it was triggered by a GitHub push or started manually from the dashboard.
Triggers
A deployment can be triggered three ways:
| Trigger | How it starts |
|---|---|
| GitHub push | A push webhook from the Theme Deploy GitHub App queues a deployment for the pushed branch. |
| Manual deploy | The sync button on a dashboard row re-deploys that branch at its current HEAD. |
| First repository selection | When you first select a repo, the default branch is deployed automatically. |
Deployment statuses
Deployments move through the following statuses, visible on your dashboard:
| Status | Meaning |
|---|---|
queued | The deployment has been created and is waiting to be prepared. |
pending | Checks passed; waiting for a deploy worker to pick it up. |
in_progress | Files are being cloned and deployed to Shopify. |
completed | Success — a preview link is available. |
failed | Something went wrong. Check the deployment log. |
plan_limit_exceeded | Your plan's monthly usage limit was reached. See plans. |
The dashboard updates in near-real time — no refresh needed.
The pipeline
When a deployment runs, Theme Deploy:
- Clones your branch from GitHub using a short-lived installation token. The
config/settings_data.jsonandconfig/settings_schema.jsonfiles in the checkout are removed. - Downloads your live theme's settings (
settings_data.jsonandsettings_schema.json) directly from Shopify and injects them into the checkout. This means changes merchants make in the Shopify theme editor are never overwritten by a deploy. - Chooses a target theme:
- If the pushed branch is your production branch and auto-publish is enabled, the target is your live theme.
- Otherwise, the target is the branch's preview theme (created on the fly if needed).
- Uploads the theme files to Shopify.
- Records a full log, viewable from the dashboard for every deployment.
Auto-publish
Auto-publish controls whether pushes to your production branch update your live theme. It is off by default when you first connect a repository — turn it on from the dashboard once you're confident in your setup. While off, all branches (including the production branch) deploy to preview themes only.
Concurrency limits
To keep deployments reliable, Theme Deploy limits each store to 3 concurrent deployments. Extra pushes stay queued until a slot frees up. Rapid consecutive pushes to the same branch each produce their own deployment, executed in order.