How to test changes on a staging site before going live

TeleportHQ gives your project a second, private address called Staging, for example https://sunny-bakery-staging.teleporthq.app. Publish your changes there, check them, and when you're happy click Make it live. Your live site then serves the exact build you tested, without rebuilding. Your live site and your custom domain don't change until you do that.

Before you start#

• Plan. Staging works on Trial, Pro and Premium. If your workspace's trial or subscription has ended, the Staging tab shows a PRO badge and "Staging environments are available on paid plans."
• TeleportHQ hosting only. Projects published to your own Vercel account have a single environment and can't use Staging.
• Role. You need the Owner, Admin or Designer role.

Steps#

1. Publish to Staging#

1. Open your project in the editor.
2. At the top right, click Publish.
3. In the window's left menu, make sure Publish is selected.
4. At the top, click Staging. The window opens on Production every time, so check this each time.
5. Check the staging address under Staging. Before your first staging publish, it shows the address your staging site will get.
6. At the bottom, click Publish to Staging. A progress bar next to the button shows each step of the publish.
7. Wait for the message: "Your staging site is ready at: https://… — your live site has not changed."
8. Click the staging address to open it, and check your changes.

2. Make the staging version live#

1. In the Publish window, click Production at the top.
2. Find the badge Staging is ahead of your live site, right under your live site's address at the top of the window.
3. Click Make it live next to it.

You can also do this from the deployments list: open Deployments, click the ⋮ menu next to a finished Staging deployment and click Promote to Production.

Check that it worked#

A message appears: "Your live site now serves the build you tested. Nothing was rebuilt, so it is exactly what you checked." Open your live address or custom domain: it shows the version you checked on staging. The Staging is ahead of your live site badge is gone.

Badges you may see#

• Staging is ahead of your live site (on Production): staging has changes your live site doesn't have yet.
• Your live site is ahead (on Staging): you published to Production more recently. Publish to Staging to bring it up to date.
• Unpublished changes: you edited the project since the last publish to that environment.

Troubleshooting#

"Staging environments are available on paid plans. Upgrade to test your changes on a private URL before they go live." Your workspace has no active plan, so it doesn't include Staging. Click Upgrade to publish to Staging or Upgrade Now to choose a plan.

"The staging build could not be kept separate from your live site, so it was cancelled. Your live site was not changed — please try again or contact support." Click Publish to Staging again. If it keeps happening, write to hello@teleporthq.io.

"There is no staging deployment to promote to production" or "This deployment is not finished building yet, so it cannot be made live" Publish to Staging first and wait until it finishes, then try again.

Good to know#

• Search engines ignore staging, and your custom domain never points at it: "Search engines are told to ignore this address, and your custom domain never points at it."
• "Private" doesn't mean locked. On Pro and Premium, anyone who has the staging link can open it, unless you turn on password protection: the password covers every address of your project, the staging one included. On the trial, every publish, to Staging too, is password-protected, so the staging address asks for the same password as your live site.
• Same build, same data. Staging is built exactly like your live site and uses the same data. Anything you submit on staging, such as a form entry, a new account or a test order, is saved with your real data.
• On a trial. A TeleportHQ trial's staging address ends in .teleporthq.app, like its live address. After the workspace subscribes, the next publish to Staging moves it to .teleporthq.site.
• Promoting doesn't publish new edits. Make it live serves the build that is on staging. Edits you made after publishing to staging need another publish.
• Unpublish leaves staging alone. Taking your live site offline with Unpublish site (on Production) keeps your staging address working. See How to take your site offline (Unpublish).
• To undo a bad release, see How to go back to an earlier version of your live site.