Deployments

How deployments work

A deployment takes a release's changeset and applies it to one or more target Shopify stores. Deployments are designed to be atomic — if a critical operation fails, the deployment can be rolled back.

Deployment phases

Each deployment moves through defined phases:

1. Pending — the deployment is queued
2. Validating — the changeset is validated against the target environment
3. Building graph — the dependency graph is computed
4. Executing — changes are applied to Shopify in dependency order
5. Completed — all changes applied successfully

If any phase fails, the deployment transitions to a failed state with detailed error information. Failed deployments can be retried.

Dependency resolution

Before writing any changes, Flux builds a dependency graph of all objects in the changeset. This ensures objects are created and updated in the correct order.

Write layers

The dependency graph is decomposed into layers. Each layer contains objects that have no dependencies on objects in the same or later layers. Layers execute sequentially, but objects within a layer are processed in parallel.

Example ordering:

1. Layer 1 — metaobject definitions, metafield definitions
2. Layer 2 — metaobject entries (depend on definitions)
3. Layer 3 — products, pages, blogs (may reference metafields)
4. Layer 4 — articles (depend on blogs)
5. Layer 5 — collections (may reference products)
6. Layer 6 — menus (may reference collections, pages, products)

Circular dependency resolution

When circular references are detected (e.g., metaobject A references metaobject B, which references A), Flux uses a two-pass strategy:

1. First pass — create all objects without the circular reference fields
2. Second pass — update the objects with the circular references now that all targets exist

This is handled automatically — you don't need to structure your data to avoid cycles.

Operation tracking

Every individual write operation within a deployment is tracked with:

• Object type — product, collection, page, etc.
• Operation — CREATE, UPDATE, or DELETE
• Status — pending, applied, skipped, failed, or reverted
• Canonical path — the file path identifying the object
• Shopify GID — the target store's GraphQL ID for the object

This granular tracking means you can see exactly which objects were touched, in what order, and whether each succeeded or failed.

Rollback

If a deployment needs to be reversed, Flux creates a revert release from the pre-deployment state. This creates a complete audit trail — the original deployment and the rollback are both recorded as separate releases.

You can also retry failed deployments or retry individual failed operations within a deployment.

Next steps

• Understand permissions required for deployments
• Explore the API reference for programmatic deployment triggers