Waymaker Host

How Your Solution Releases

Learn about How Your Solution Releases in WaymakerOS.

ReleasesLive and Staging

A Solution is everything one product needs: its apps, databases, Ambassadors, sign-in, domains and email. A release moves the whole Solution forward together, in order, and keeps a record of what went Live. This page explains the choice you make about how changes reach your customers, and what each choice means for your next merge.

You'll find it in the Solution's settings: open a Solution, choose Settings, then the Releases tab, under How this Solution releases.

Live and Staging

  • Live is what your customers see: your domains and your app addresses.
  • Staging is where a change waits before it goes Live. On After approval, every merge to your live branch builds a staged copy of the whole Solution, so you can look at it before anyone else does.

Nothing in Staging changes Live. Live changes only when a release is applied (or, on Each tool on its own, when you push).

The ways a Solution can release

Each choice says, in one line, what the next merge to your live branch will do.

  • After approval. The next merge to your live branch builds a staged copy of the whole Solution. Live changes when someone approves the release.
  • Each tool on its own. The next push to your live branch deploys each tool by itself, straight to Live. Database changes don't run, and nothing is ordered.
  • Automatically, in order. The next merge to your live branch releases the whole Solution to Live in order: database changes, sign-in, Ambassadors, apps, then domains. Only a risky database change waits for a person. See Releasing automatically.

Only an owner of the Solution can change this choice. Everyone else sees the current choice and "Only an owner can change this."

Switching to Each tool on its own removes the staged copies, because nothing is waiting for a release any more. The change is recorded in the Solution's activity.

What a staged copy is

On After approval, a merge to your live branch doesn't touch Live. Host builds a staged copy of each app instead, at its own address:

your-app--yourorg--staged.waymakerapp.com

If the app has a database, the staged copy gets its own copy of the database, and the commit's new database changes run there first, so you see the app with the schema a release would give it. Live data is never changed.

In the app's Deployments list, a staged build says Staged · waiting for release, with no links to your Live addresses. Expand it and Host says "Live hasn't changed. Release this Solution to ship it." with a link to the Solution's Releases. A Live build says Live. A preview of another branch says Preview and its branch name.

Releasing

  1. Open the Solution's settings and choose Releases.
  2. Choose Plan a release. The plan shows what will change, in order, and applies nothing yet.
  3. If the plan is right, choose Apply release and confirm.

Each step keeps the evidence of what went Live. If a release stops part-way, it says so, and you can resume it or abandon it with a reason from the release history.

Promote on an app in a Solution on After approval doesn't ship that app on its own. Host tells you the app releases with its Solution, and points you to the Solution's Releases.

Releasing automatically

On Automatically, in order, nobody has to plan or apply a release. When a merge to your live branch has built its staged copy, the Solution plans one release for that merge and applies it, in order. Merges that arrive while a release is running wait their turn.

What you are agreeing to

Choosing Automatically, in order hands release to whoever can merge to your live branch. Before you confirm, the settings show the exact sentence that is recorded, naming each repository and branch. For example: "Anyone who can change main in your-org/your-repo can release this Solution, migrations included, when the person who merged is a releaser of this Solution, or main requires a reviewed pull request and blocks force-push."

Only an owner can confirm it, and the change is recorded in the Solution's activity with who confirmed it and when.

Why protecting your live branch matters

A release goes ahead on its own only when your live branch requires a reviewed pull request and blocks force-push, with nobody able to bypass those rules. Otherwise every merge still plans its release, and then waits for a person.

The settings tell you where you stand:

  • "main is unprotected" means the rules aren't there yet. Use the Branch settings link to add them in your repository. Host links to the setting and never changes it for you.
  • "We couldn't read main's protection" means Host couldn't check just now, or isn't allowed to read your branch rules. It doesn't mean the branch is unprotected. Until Host can read it, releases wait for a person.

Database changes

A database change goes ahead on its own only when the staged copy has already run that exact file, and every statement in it is a standard additive change: creating a table, an index, a sequence, a list type or a schema; adding one of a few common extensions (pgcrypto, uuid-ossp, citext, pg_trgm, hstore or vector); adding a column or a rule to a table; setting a column's default; or a comment (some of these still wait when they would lock a table, see below). Anything else waits for a person. That includes adding, changing or removing rows, removing or renaming anything, row-security rules, who can access what, and anything that can't be read clearly. The release says which file and which kind of statement, never the SQL itself.

Some changes always wait for a person, even when the staged copy ran them, because they would lock a table that already has rows while it is scanned. The release names the statement, and the safe form to use instead where there is one:

  • building an index on an existing table: building an index on an existing table blocks writes while it builds, so this waits for a person to apply;
  • adding a foreign key or a check without NOT VALID: add it NOT VALID, then VALIDATE CONSTRAINT in a later migration;
  • adding a unique key or primary key in place: this builds an index too, so it waits for a person to apply;
  • making a column required (SET NOT NULL), or adding a generated column or a new column with its own constraint;
  • adding a column whose default calls a function other than now() (such as gen_random_uuid()), or a serial column: every existing row is filled in under a lock that blocks reads and writes. Add the column with no default or a fixed one, then set the default and fill the rows in batches.

None of these waits when the table is new in the same release, because a new table is empty.

If your app's end-user sign-in is on, a release that creates a new table in public always waits for a person. Turn row-level security on for the table in the same release (ALTER TABLE … ENABLE ROW LEVEL SECURITY): without it, every signed-in user could read and change that table. Turning it on is itself a change to who can see what, so the release still waits for a person to apply it. When it does, the release says which new tables have no row-level security.

If someone changed your Live database after the release was planned, the release stops before touching it and is marked refused. Merge again to plan a fresh one.

Before an automatic database change runs, or an automatic sign-in deploy, Host takes a restore point of your database. If the release resumes, it keeps that first point, and checks it is still there before it goes on. If it can't, nothing runs, the release stops as refused, and its owners and releasers are told so a person can apply it. If something goes wrong after the change, an owner or releaser of the Solution can restore the database to that point from the release. Restoring overwrites everything written to the database since then. Restore points are kept for 7 days after the release finishes; a release that stopped partway keeps its points for 30 days. A database change a person applies takes no restore point. When an automatic change fails, the release says what kind of error it was and which file stopped it, not the database's own message.

Once automatic database changes are switched on, a safe database change that the staged copy has already run goes ahead on its own. Until then, and for anything else, the release waits for a person: it says "automatic database changes aren't switched on yet" or names the file and why.

When a release can't go ahead

The Solution's home page says what happened to the latest merge:

  • Automatically, in order: the last merge released, or nothing is waiting.
  • Needs a releaser: the release is planned and waiting for an owner or releaser, with the reason. Open Releases, check the plan and apply it, or merge a change that replaces it.
  • Release refused: the release would have been unsafe or couldn't be built, so nothing was applied. Fix the cause and merge again.
  • The last release failed: a step stopped it. Releases says which one.
  • Release expired: nobody applied the waiting release within 14 days, so it was never applied. Merge again to release.
  • A release is unfinished: an earlier release stopped part-way. Resume it or abandon it with a reason first. New merges wait behind it.

Owners of your organisation and the Solution's owners and releasers get an email each time a release is refused, waits for a releaser, stops unfinished or expires. It gives the reason, the commit, who merged it and the one thing to do next, with a link to the Solution.

Set up staging

Host can't create a staging branch for you yet. Create one in each repository the Solution builds from, starting from your live branch's current commit. Pushing to staging then builds its own preview, so you can try a change before it goes Live. This page will say when Host can set it up for you.

Rolling back

Rolling back is always available, whichever choice your Solution is on. Open the app's Deployments, choose an earlier Live deployment, then Roll back. See Deployment History. On After approval, a roll back outside a release is recorded in the Solution's activity, so it is never silent.