App environments: build and test without touching your live app

Where to find it #

Go to Settings > Environments, or press Set up environments in the top bar. The app owner adds the first environment.

When to use it #

• A big change on a live app. Rebuild a page, restructure a table or rework a workflow without users seeing it half-done.
• Testing emails, payments and integrations. In an environment they're caught instead of reaching real customers (see What's sent from an environment).
• Change control. Review exactly what will change, require someone's approval, and keep a record of every release.
• Training or demos. A Training copy with sample or masked data that people can click around in.
• An urgent fix while other work is in progress. Production can still be fixed directly while Staging holds unfinished work.

For a small change on an app with few users, building straight in Production is fine. Environments earn their keep once real people depend on the app.

Add an environment #

1. Choose the kind and a name Pick Development, Staging, UAT, QA, Training or a custom one, give it a name and a colour. The colour shows as a stripe across the builder, so you always know where you are.
2. Choose where the design comes from Copy from Production, or from another environment.
3. Choose the data Empty, Sample (the newest records of each table), Full copy, or Masked (a copy with personal details scrambled). Options your plan doesn't include are marked Not in your plan.
4. Choose the app users We recommend one test user per role, so you can sign in as each role. You can also copy real users with masked emails. Login sessions are never copied.
5. Choose who can open it Builders only, Builders and test users, or Anyone with the address.
6. Create it Press Create environment. It's built in the background, and you can keep working.

Each environment has its own address and is named after your app, for example "Orders (Staging)". Passwords and keys for your email server, payments, sign-in and file storage aren't copied, and scheduled tasks start off. Uploaded files are shared with Production for reading; deleting a file in an environment never deletes it from Production.

Promote changes to Production #

When your changes are ready, open the environment menu in the top bar and choose Promote changes.... The release goes through a few short steps:

1. Review changes You see what was added, changed and removed. Items changed in both places are flagged so you can pick which version wins, one by one or all at once.
2. Fill in what Production needs If a change needs a value that only Production can have, such as a setting that's different per environment, you're asked for it here.
3. Add notes, and get approval if required Describe the release. If your app requires approval, an approver confirms it before it's applied.
4. Apply The release is applied to Production, and a version of Production is saved just before, so you can go back.

Fields you removed go to Production's field trash with their values, so nothing is lost. A workflow or task that already exists in Production keeps its on/off status there.

Roll back and stay in sync #

• If a release fails, Production is put back automatically.
• Roll back... on a finished release (under Releases) returns Production's design to how it was before. Records aren't affected.
• Sync from Production brings changes made directly in Production into your environment, so you don't overwrite them later.
• Versions saves snapshots of the design you can compare and restore. A version is also saved before every release.
• Refresh data... replaces an environment's records without touching its design. Reset from Production... rebuilds it from scratch; work done only there is lost, and it gets a new address.

What's sent from an environment #

Outside Production, anything that would reach the outside world is caught in the Outbox instead of being sent: emails, text messages, webhooks, integration calls and payments. The Outbox keeps them for 14 days so you can check exactly what would have gone out, and you can deliver one to yourself.

• Emails to your app's builders and the environment's test users are sent for real, so you can test them. Add other addresses under What may be sent for real.
• With Stripe test keys, payments run in test mode. Production's live keys are never used.
• Scheduled tasks don't run unless you turn on Run schedules here.

Who can do what #

By default, everyone who can build Production can open every environment. Change that per person under Access & policy, where you can also protect Production from direct edits and require approval for releases. How many environments you can have, the data options and the approval features depend on your plan, and environments count toward your Production app's plan.