Environments and previews
Add staging to try changes before visitors see them, promote exactly the tested build to production, and get a preview for every GitHub pull request.
Updated 17 Oct 20264 min read
Every project is its production: what your visitors see. Next to it, you can add staging and other environments, each a full copy of the project with its own apps, databases, variables and address, to try changes on. And every pull request on GitHub can get its own preview.
Add staging
Open your project and choose Manage environments from the environment switcher at the top.
Choose Add staging, check what's copied, and confirm.
What's copied, and what never is:
| Copied | Never copied |
|---|---|
| Your apps, with their code, limits and settings | Production's variables: staging starts with none, so a test can't send real emails or take real payments |
| Your databases' kinds, empty | Production's data: its databases start empty |
| A free address of its own, hidden from search engines |
Choose Add an environment for another copy, like demo for a client. A project can have up to 5 environments besides production.
Production is marked in red wherever it shows, and every screen says which environment you're in. Staging is charged like any other services, and sleeps when nobody uses it.
Promote a build to production
When a change works on staging, open staging's app and choose Promote build 12 to production (with its own number). Production gets exactly the build you tested, the same files byte for byte, without building again, with production's own variables. Production's deployments then say "Promoted from staging, build 12", and you can roll back as usual.
Shared variables
On the Environments page, Shared variables are set once for every environment: your mail provider's address, for example. An app's own variable with the same name wins, so staging can have its own MAIL_PASSWORD for a test mailbox.
Data on staging
Staging's databases start empty: run your migrations and test data on them. Or choose Copy production's data, from its newest copy, so production isn't slowed down.
Names, emails and orders will be on staging too. Anyone you give staging's password to can see them.
Previews of pull requests
When your production app deploys from GitHub, each pull request on its repository gets a preview:
built from the pull request, and built again on each push;
with that app only, its databases empty, never with production's data;
with none of production's variables, unless you mark one Also for previews on the project's Variables tab;
with Migrate on deploy off;
its address posted as a comment on the pull request, and kept up to date: building, live or failed;
removed when the pull request closes, or after 7 days without a push.
A project has up to 10 previews at once. They sleep when nobody uses them.
A pull request from someone else's fork never runs until someone who manages the project approves it with Approve and build: a stranger's code could otherwise read your preview's secrets.
You can also run any earlier version as a preview, with Run this version as a preview.
A password and search engines
Search engines are always told not to show staging and previews. On an environment's Address card, Ask visitors for a password makes anyone opening it type a password first: good for showing a client. It's on for previews unless you switch it off. The password needs at least 8 characters and is kept only as a hash; a visitor who types it stays in for 12 hours.
WordPress and PHP sites
A site's staging is a copy of its files and database, to try plugins, themes and updates. Choose Copy to staging, try your change, then Push to live:
Files: themes, plugins and uploads go to the live site.
Database too, only if you tick it. The live site may have new orders since the copy: pushing the database replaces them with staging's, and the screen warns you with their number.
Before pushing, a copy of the live site's files and database is kept for 7 days, so you can go back.
Example: Asha's new checkout
Asha builds a new checkout on a branch and opens pull request #42. Once it's built, a comment on the pull request gives the preview's address. She sets a password on its Address card and sends it to a friend to test. Her friend finds a bug; she pushes a fix, and the preview builds again. After merging, she deploys the new code to staging, tests once more, then chooses Promote build 12 to production. Her customers get the exact build she tested.