Versions and test hosts

Ship through versions

Every push creates a numbered, immutable version on a branch. The live version does not change until you promote a version. Push, then review the changes before promotion:

substrio push -m "add discount field"
substrio diff            # against the current live version

See versioning for branches, tags, merges and the full verb list.

Try on a sandbox or test host

A sandbox runs a version you choose against a copy of your app's data, without changing the live app. Bind a host to a new sandbox running the version you pushed, and test it end to end before promotion. Over MCP, call these tools in order:

[
  {"name": "substrio_env_host_set", "arguments": {"host": "my-app-v2.substrio.com", "environment": "dev", "version": 2}},
  {"name": "substrio_live_set", "arguments": {"from": "my-app-v2.substrio.com"}},
  {"name": "substrio_env_host_remove", "arguments": {"host": "my-app-v2.substrio.com"}}
]

The first call creates the dev sandbox running version 2 and binds the host to it. https://my-app-v2.substrio.com then runs version 2 on the sandbox's data, while my-app.substrio.com continues to serve the live version. See test-hosts for all host operations.

Promote

Once testing is complete, the second call promotes the version running on the test host. The third call releases the host. To promote by version number instead, use the CLI or call version.live.set with version in place of from:

substrio promote 2

Every promote backs your app's data up first, unless you pass --no-backup.

Roll back

substrio rollback (version.live.set with version: "previous") restores the version that was live before the last promotion. It changes code only, leaving data as it is. To restore data as well, run substrio restore (version.restore). It restores the backup taken at promotion and makes the version that was live at that time live again. Keep promotions small so a rollback undoes one change.

Branches and tags

Push to a named branch (substrio push --branch feature/x) to try a change apart from main; merge it in with substrio merge FROM --into NAME once it is ready. Tag a version that ships to customers (substrio tag v1.4.0) so you can always find exactly what ran, independent of later pushes to the same branch.