Apps

Preview Environments

Learn about Preview Environments in WaymakerOS.

PreviewsPromoteRollback

Deploy any branch of your app to its own isolated URL — test a change on a real, live copy before it reaches production. When you're happy, promote it. If a deploy goes wrong, roll back in one step.

Previews: one URL per branch

Push a branch, and Host can deploy it to a preview — a separate live version at its own address, so your team can review work in progress or test a change without touching production.

  • Each preview gets its own URL: your-app--yourorg--branch-name.waymakerapp.com.
  • Production keeps running untouched at its normal address.
  • Redeploying the same branch updates the same preview — the URL is stable.
  • Only people in your organization can open a preview, and only after signing in to Waymaker. Who exactly depends on the preview's data:
    • A preview with a real copy of the data is open only to the owners and releasers of the app's Solution.
    • A preview with the masked copy is open to every member of your organization.
    • A preview with no database is treated like one with real data: owners and releasers only.
  • Nobody else can open a preview, even when the app itself is on the web for everyone. That includes anyone who isn't signed in, a guest, and an API key.
  • What anyone else sees. Someone who opens a preview's address in a browser is asked to sign in to Waymaker. If they can't open that preview, they're told it isn't available to them. So a pull request's author who isn't in your organization can't open the preview of their own pull request.
  • An address shows that a preview exists. Someone who isn't signed in is asked to sign in at a preview's address, but sees a "not found" page at an address with no preview. They never see anything from the preview itself. Live apps that are open only to your workspaces work the same way.
  • Nobody can sign in to a preview with a Live account: its sign-in data is always emptied.

Manage previews from the app's Previews view, or with the Waymaker tools from your editor.

Previews get their own database

If your app has a database, each preview automatically gets its own isolated copy — a branch database. Your preview reads and writes that copy; production data is never touched. Migrations you add on the branch apply to the branch copy only, so you can test a schema change safely.

A preview's copy never includes sign-in data. Before a preview can use its copy, Host empties the tables that hold your app's sign-ins: tables named user, session, account, verification, two_factor, jwks and auth_admin_audit. Where your own tables refer to user, those people are kept but anonymised (an @users.invalid email and the name "User") so the rest of your data still fits together. Nobody can sign in to a preview with a production account, and no production session or signing key ever reaches one. This applies to every preview, including yours. If your app has its own tables with one of those names, a preview's copy of them will be empty too. If Host can't confirm the sign-in data is gone, the preview gets no database at all.

Previews can't send email. A preview never gets your app's sending key, Live or Staging, so nothing a preview does can email anyone. If a sending key is set in one of your Staging or preview variables, the preview isn't built, and Host names the variable to remove it from.

Who opened the pull request matters too. A pull request from an owner or releaser of the app's Solution gets a copy of the rest of the data. A pull request from anyone else, a fork included, gets the Solution's masked copy, or no database if there isn't one.

If a preview's database can't be created for any reason, the preview still deploys (against no database) rather than failing — so a preview is never blocked.

A preview is one app's part of a branch's copy. For the whole Solution's copy, the Branches section on the Solution's home page, and how long a quiet copy lives, see Every Branch Gets Its Own Copy.

Promoting a preview to production

Happy with a preview? Promote it. Host runs a production deploy built from that branch, so exactly what you tested becomes what's live.

One thing to know about the database: if your preview added migrations that production doesn't have yet, promoting surfaces those pending migrations for you to apply — it never runs them against production automatically. You review them, then apply them deliberately. Your schema is never changed behind your back.

Rolling back

If a deployment causes a problem, you don't need to hunt through git or craft a revert. Roll back to a previous version and Host redeploys it directly — production is restored in one step, no new commit required.

Roll back from the app's Deployment History, or with the Waymaker tools.

Cleaning up

Previews are torn down automatically so they don't linger or keep costing you:

  • Remove a preview yourself from the Previews view.
  • When the branch's pull request is closed or merged, its preview and branch database are removed.
  • A nightly cleanup catches any that were missed.

Each active preview with a branch database adds a small daily amount to the database's cost while it exists, and stops the moment it's torn down — see Database Billing.

Next Steps