Guide

Previews

Every branch gets a running URL, for eight hours

PREVIEWS

A push to main is production. A push to **any other branch** deploys that
branch too, at its own hostname, from the blueprint at that commit. Nothing
opts in and there is no file to edit — the branch existing is the whole of
it.

This is what to offer somebody who wants to see a change before it is live.
You push the branch, you hand them a URL, and they look at the thing itself
rather than at your description of it.

WHERE IT IS

  one service      https://<branch>--<name>.saasie.app
  more than one    https://<service>--<branch>--<name>.saasie.app

The branch part is not the branch name — it is a slug of it, cut short, with
four hex characters of a hash on the end so that "fix/login" and "fix-login"
cannot land on the same URL. **Do not construct it yourself.** Push, then
read it:

  saasie app <name> build list           the newest build, and its branch
  saasie app <name> build show <number>  its URL

WHAT IS DIFFERENT ABOUT ONE

  Its databases are empty. Every entry under "databases:" is provisioned
  fresh for the preview and dropped when it expires. It never gets
  production's data, and never gets production's connection details — so an
  app that needs rows to show anything has to seed them itself.

  It is the same Saasie. Same service token, same batteries, same secrets.
  Its calls carry SAASIE_DEPLOYMENT in the environment — "production", or
  the preview's slug — so an app that wants to behave differently on a
  branch can read it, and analytics events are tagged with it either way.

  It may read, and may not destroy. A preview can send mail, write
  analytics, read secrets, provision and read files, enqueue and consume.
  It cannot set a secret, mint a setup link, delete a file, or ack a
  message — every one of those outlives the preview by taking something
  production still needs. Those calls answer 403, and that is the preview
  working correctly rather than a bug in your app.

  Its mail comes out of the same five a day. Six branches do not get
  thirty-five mails.

  No custom domain routes to it. Only main gets the hostnames a customer
  proved.

WHEN IT GOES AWAY

Eight hours after its last deploy. Pushing to the branch again resets that,
so a branch being worked on stays up and an abandoned one does not. Deleting
the branch tears it down at once.

Three previews per Saasie. A fourth branch deploying evicts whichever has
gone longest without a deploy — so the URL goes to whoever is working now,
rather than the newest push being the one refused.

A push whose hostname would not fit in 63 characters is failed at push time
with a message naming what to shorten. That is a long service name plus a
long Saasie name plus a long branch name; shortening the branch is the fix.

THE ONE THING THAT SURPRISES PEOPLE

A preview build does not supersede a production build, and two branches do
not supersede each other. So "build list" can show more than one build that
is live, and they are all correct. The branch column says which is which,
and only the one from main is what your user sees.

Builds still queue behind one another, though — the builder is one at a
time per Saasie. A preview pushed while production is building waits.

The same text, on your machine: saasie docs previews