How deploys move from code to traffic

A deploy turns a selected Git revision or captured Workspace into an immutable release image. synsmarts validates and builds that image, handles any Magento database changes, starts the replacement separately, and moves traffic only after the replacement is ready.

The main stages

Every deploy progresses through customer-visible phases:

1. Pending waits to start.
2. Validating checks the requested source and App configuration.
3. Classifying determines whether database changes need special handling.
4. Building prepares the runnable release.
5. Migrating applies database changes when required.
6. Rendering prepares the target configuration.
7. Deploying starts the replacement release.
8. Promoting moves traffic after health checks pass.
9. Cleaning up removes temporary release resources.

Not every deploy reaches every phase. A code-only release skips migration. The deploy finishes as Complete, Failed, Restore failed, Cancelled, or Superseded.

What zero downtime means

For a code-only release, synsmarts starts the replacement beside the currently serving release. The replacement must become ready before promotion. If validation, build, synchronization, or rollout checks fail before promotion, the previous release keeps serving.

For a proven additive Magento migration, the previous release also keeps serving while the compatible database expansion runs and while the replacement starts. This path has no planned interruption and doesn’t intentionally return a maintenance page.

Zero downtime doesn’t mean zero observable effect. A live additive DDL operation can briefly wait for a MySQL metadata lock, and Magento can rebuild caches after setup:upgrade. synsmarts checks three times for transactions older than 30 seconds before live DDL and fails the deploy if they persist.

Static classification can’t prove that breaking or unclassifiable Magento changes are safe against one shared database. A read-only status probe checks the live schema before a notified maintenance window begins. A clean schema promotes without the window or notification; migration-required and probe-unavailable results use the existing windowed path.

How Magento database changes are detected

Magento uses two static checks plus a runtime check. WordPress doesn’t use this classifier.

1. Detect whether migration-bearing files changed

For Git deploys, synsmarts compares the currently serving commit with the resolved candidate commit. The comparison is against immutable commit SHAs, even when the customer selected a branch or tag.

The deploy is migration-bearing when the change includes a known carrier such as composer.json, composer.lock, db_schema.xml, db_schema_whitelist.json, module.xml, app/etc/, Setup/, or Patch/. When none of those paths changed, the deploy is code-only.

For Workspace deploys, the snapshot producer calculates a Workspace schema fingerprint from the same migration-bearing paths. When that fingerprint matches the currently serving Git commit, the deploy is code-only. A missing Git baseline, a fingerprint mismatch, or a .deployignore file makes the result unknown rather than guessing that it is safe.

2. Classify the built Magento release

When migration-bearing files changed, synsmarts builds the candidate image and compares its post-build schema inventory with the serving image. This catches Composer-installed modules under vendor/, which a repository diff can’t see.

The inventory includes:

• merged db_schema.xml declarations;
• db_schema_whitelist.json files;
• content fingerprints for PHP under Setup/ and Patch/.

Added tables, nullable or defaulted columns, and ordinary indexes can be classified as additive. Drops, renames, changes to existing columns or constraints, whitelist-only changes, and changed Setup or Patch PHP receive breaking treatment. By default, additive DDL against a table estimated above 1,000,000 rows also receives breaking treatment. If either image inventory or the database-size check is unavailable, classification remains unknown and routes to the status probe rather than being treated as safe.

3. Check the live database before changing it

The runtime check runs from the new image. Breaking and unknown candidates use a separate read-only setup:db:status probe before notification, maintenance, scheduled-work pause, or the real migration Job. If Magento reports that the database is already current, the deploy is a no-op and promotes without a maintenance window or notification.

When migration is required or the probe is unavailable, the deploy enters the existing notified maintenance window. The managed migration Job runs:

Managed Magento migration

bin/magento setup:db:status
bin/magento setup:upgrade --keep-generated
bin/magento setup:db:status

Don’t run this production migration manually. The managed Job is tied to the deploy record, backup, maintenance state, and rollback-safety flags.

What happens on each deploy path

Path	Database behavior	Traffic behavior
Code-only	No migration Job or pre-migration backup.	The old release serves until the replacement is promoted. No planned interruption.
Additive	Take a pre-migration backup, pause scheduled work, and run the migration from the new image.	The old release keeps serving. No planned interruption.
Breaking	Take a pre-migration backup and run a read-only status probe. A clean schema skips the real migration Job; migration-required and probe-unavailable results use the windowed Job.	A clean schema promotes with no maintenance window or notification. Otherwise customers receive the maintenance page until promotion.
Unknown	Use the same probe-first execution as breaking because static compatibility couldn’t be proved.	A clean schema promotes with no maintenance window or notification. Otherwise customers receive the maintenance page until promotion.

The maintenance notification is sent only when the probe doesn’t prove the schema is clean and the deploy enters the window. The notification is informational; the deploy doesn’t pause for approval after it starts.

How migration failures recover

Every non-code-only Magento path takes a dedicated pre-migration backup before the migration Job can start.

An additive migration runs while the previous release accepts writes. Therefore an additive failure is not restored from the pre-migration backup: restoring would discard valid writes made during the attempt. The deploy fails, the previous image remains live, scheduled work resumes, and any earlier compatible statements from a multi-statement migration can remain.

When a breaking or unknown candidate needs migration, the Job runs after traffic is drained to maintenance. If it fails before promotion, synsmarts stops the migration Job, restores the pre-migration backup, returns the previous release to service, and marks the deploy failed.

Danger

If the migration Job can’t be confirmed stopped, the backup restore fails, or maintenance can’t be safely removed, the deploy ends as Restore failed. Maintenance stays on so a possibly half-migrated database is not served. Contact support; do not retry or bypass the maintenance page.

Promotion protects the active release

After database handling, synsmarts renders the replacement configuration, synchronizes it, waits for the preview release, and explicitly promotes it. Traffic doesn’t move merely because a build or configuration commit succeeded.

Rollback depends on data compatibility

A code-only or additive rollback promotes the previously built immutable image without rereading Git or Workspace and without restoring the database.

After a successful breaking or unknown migration has served traffic, the prior image and current database may no longer be compatible. Any rollback that could discard newer customer data requires an explicit data-impact decision; synsmarts doesn’t infer consent from silence.

For procedures, see Manage deploys and Roll back a deploy.