Skip to content

Preview environments

Each pull request gets a temporary copy of your app at its own https address. A member's pushes redeploy it. Anyone else's pull request waits for a member to approve it. When the pull request merges, the environment that deploys its target branch, usually production, deploys the merge with the setting changes the preview made, and the copy and its data are deleted. Closing the pull request without merging deletes it too.

The dashboard calls these PR environments.

Previews work for services that deploy from GitHub through the Ployz GitHub App. Until one does, Settings → Project has no PR environments section. (The quick start's example deploys without the app, so connect GitHub and deploy your own app first.) The app also needs Pull requests: read and Checks: write on the repository: if your repository shows Needs permissions approved on GitHub, open it, click Approve on GitHub, and have the installation's owner approve them.

  1. Open Settings → Project, and under PR environments click your repository.
  2. Click Enable PR environments. Under Start from, pick the environment each pull request starts from, usually production.
  3. Under Services, click each service a pull request should get its own copy of, like postgres. Services that deploy from this repository always run the PR's code.
  4. If pull requests get a new, empty database, add a Setup command to seed it, like pnpm db:seed.

The panel saves as you go. Pull requests already open get a preview on their next push.

Two more switches sit in the panel. Delete when the PR closes is on by default. Enable bot PR environments is off: turn it on to preview pull requests from Dependabot, Renovate and other bots.

A preview runs the pull request's code next to your services, with any secrets you set in it. So Ployz deploys a pull request on its own only when a member of your Ployz organization wrote it, from a branch of the repository itself. A pull request from a fork, or from someone outside your organization, reads Needs approval under Open now, with its commit like a1b2c3d. Until a member approves it, nothing builds and no preview exists.

Ployz knows a member by the GitHub account they signed in with. A member who signed in some other way has their pull requests wait too. Ployz checks again each time it picks a new commit from Git to deploy, so once the author leaves your organization or unlinks GitHub, their pull request reads Needs approval from the next push, CI result, or deploy that picks a new commit from a Service's branch in your organization, and its new commits wait for a member to approve them. A deploy that reuses commits already picked, such as a retry, doesn't check. If the author comes back, their pull request deploys on its own again from its next push.

To deploy it, read the pull request's changes on GitHub, then click Approve deploy beside it. From the CLI, run ployz env pr approve 142. The approval covers that one commit. A new push reads Needs approval again, with the new commit, and the preview keeps running the commit you approved until you approve the new one. If someone pushed after you loaded the page, Approve deploy is refused with This pull request has a newer commit. Approve that one.

If the approval couldn't make the preview, for example because your organization has no servers yet, the pull request stays under Open now. Fix the cause, then approve it again.

Bots' pull requests from the repository itself count as a member's once Enable bot PR environments is on. A bot's pull request from a fork still needs approval.

ployz env pr lists each open pull request with where it stands, like #142 needs approval a1b2c3d or #140 deploys.

Previews on servers that enforce device approval

Section titled “Previews on servers that enforce device approval”

Servers with device enforcement on open a preview only under a preview rule you approve from an approved device. It works like deploy on push: approve it once from the environment previews start from, for the services that build from your repository, naming the GitHub accounts whose pull requests deploy without a review:

ployz github preview approve web --env production --trust alice --trust bob

It prints what every preview will run, then signs it with your device key:

Approving previews of production:
  repository  acme/web, parent branch main
  builder     getployz/build/.github/workflows/build.yml@39e1f488e492c0641e520777e481e8f5b266985b
  urls        <service>-pv-<id>.acme-x7q2.ployz.app
  trusted     alice (1109914), bob (2207431)
  servers     2 in the cluster
  web
    builds    Dockerfile Dockerfile, context ., platforms linux/amd64, with the Actions cache, build args LOG_LEVEL=info, build secrets DATABASE_URL
    reads     DATABASE_URL from production
    variables DATABASE_URL=(sealed "DATABASE_URL" from environment 0f8fad5b-d9cb-469f-a165-70867728950e), LOG_LEVEL=info
    ports [{"container_port":80,"hostname":"web-pv-<id>.acme-x7q2.ployz.app","http_protocol":"https","load_balancer_port":443,"mode":"ingress"}]
    setup     runs once, on each preview's first deploy, with
      pre-deploy ["/bin/sh","-c","pnpm db:seed"]
    generated SESSION_SECRET=${{ secret(32, "a-zA-Z0-9") }}, new in each preview
Approved. Pull requests to acme/web by the accounts shown now open a preview of web.

From then on a push to a pull request's branch, by an account the rule trusts, deploys its preview with no prompt. Each server checks the rule, GitHub's tokens, the branch's head and the settings itself, so Ployz Cloud can't put a preview's code into production or hand it a production secret the rule doesn't name.

  • Trusted accounts are only the ones you name with --trust, by GitHub login or numeric ID. Ployz reads each one from GitHub and shows its login and ID, so check the list before you rely on it. Without --trust the rule trusts nobody, and every pull request waits for a review. Joining your Ployz organization doesn't add anyone: approve again with the new list when someone joins or leaves, and name every account you still trust, because each approval replaces the last one's list.
  • Each preview gets its own namespace and address, which every server works out from the rule and the branch, like pv-5a5a5a5a5a5a5a5a-3f9c2e1b7d40. A preview's generated address is web-pv-5a5a5a5a5a5a5a5a-3f9c2e1b7d40.acme-x7q2.ployz.app, not web-pr-142…. Pull requests already open keep their old address: close and reopen them once the rule exists.
  • Secrets stay closed unless the rule names them. A preview reads a sealed value from production, like DATABASE_URL above, only if production's value is set and the service's preview copy leaves it Not set. A value you set in the preview is the preview's own, and the server refuses it. Every other secret stays out.
  • Volumes a preview doesn't copy are refused. If a preview would mount production's volume, approve says so and stops. Copy the volume in the PR plan, or add --share-mounts to let every preview read and write it.
  • A saved change waits for you. After you change the settings of a service the rule covers, previews stop deploying it until you approve again. So does adding a server.
  • Closing the pull request removes its preview with no prompt. Each server checks the rule that opened it and takes off only that preview's namespace and volumes.
  • Stop it with ployz github preview end --env production. The servers refuse every preview build and deploy under the rule from then on.

GitHub builds each preview on the run its push started, and Ployz runs it again if it ended before the pull request opened. So your repository needs Ployz's rule workflow as .github/workflows/ployz-build.yml, which builds on pushes to every branch, and on a dispatch with a commit for reviewed previews. It's the same file as for automatic deploys. Organization → Builds offers it, under Update workflow, once the repository's workflow calls Ployz's rule builder. Before that, copy it from here exactly as it is:

name: Ployz build
on:
  push:
    branches: ['**']
  workflow_dispatch:
    inputs:
      cloud: { required: false, type: string }
      commit: { required: false, type: string }
permissions:
  contents: read
  id-token: write
jobs:
  build:
    if: github.event_name != 'push' || vars.PLOYZ_BRANCH == '' || github.ref_name == vars.PLOYZ_BRANCH
    uses: getployz/build/.github/workflows/build.yml@39e1f488e492c0641e520777e481e8f5b266985b
    with:
      cloud: ${{ inputs.cloud || vars.PLOYZ_CLOUD || 'https://ployz.dev' }}
      commit: ${{ inputs.commit }}

Leave the repository variable PLOYZ_BRANCH unset, or pushes to other branches won't build their previews.

A pull request from a fork, or from an account the rule doesn't trust, opens its preview but deploys nothing until you review its commit. In the PR panel its row reads Needs approval with the commit. A member's pull request that the rule doesn't trust shows no badge, but your servers still refuse its pushes, so its row offers the same review. That includes every pull request when you approved the rule without --trust. Read the pull request's changes on GitHub, then click Review and approve. The dialog lists each service the review covers and what it asks for, then every setting the review signs, like:

Review web at a1b2c3d4e5f6 (reads DATABASE_URL from the parent, builds with secrets)
  variables DATABASE_URL=(sealed "DATABASE_URL" from environment 0f8fad5b-d9cb-469f-a165-70867728950e), SESSION_KEY="${{ secret(32, \"a-zA-Z0-9\") }}"
  command ["npm","start"]
  ports [{"container_port":3000,"hostname":"web.{preview-namespace}.example.com","http_protocol":"http","load_balancer_port":443,"mode":"ingress"}]

A generated value shows as the secret(…) call that makes it, a secret the preview reads from its parent as sealed from that environment, and the preview's own namespace as {preview-namespace}, since each preview gets its own.

A line also says when the service opens its own secrets you set in the preview, when its settings differ from the preview rule because someone changed them in the preview, and when it runs setup commands again.

Approve with passkey asks your passkey once. Ployz builds that commit with your repository's build workflow, on the branch of the environment previews start from, and the preview deploys it.

  • Each server checks the review itself: your passkey's answer, the commit, the preview rule, and each service's settings. Ployz Cloud can't build or run another commit under it, or open a secret the rule doesn't name.
  • The review covers one commit. A new push reads Needs approval again, and the preview keeps running the commit you reviewed.
  • A review lasts 15 minutes. The commit must build and start in that time, or the servers refuse it: click Review again on its row. With Wait for CI on, review once CI has passed. Once a server has started the reviewed commit, it restarts it with no new review.
  • Each project reviews its own preview. If two projects preview the same repository, review the pull request in each one's PR panel.
  • Servers need Ployz 0.4. An older server refuses every reviewed preview, and the dialog names it. Upgrade it first.

When a pull request opens, Ployz deploys its preview, named like pr-142:

  • Your repository's services run the pull request's code. Every service in the preview runs one replica.
  • Each copied service with a generated address gets its own. If production's web is web.acme-x7q2.ployz.app, the preview's is web-pr-142.acme-x7q2.ployz.app. Custom domains aren't copied.
  • A push deploys the new commit, even if production doesn't deploy on push, once the pull request deploys automatically or a member approves that commit. Wait for CI and Watch paths still apply.
  • Secrets don't carry into a preview: by design, a branch never gets its parent's secret values. Each sealed variable starts Not set, and the preview deploys without it. See Set a preview's secrets.
  • A generated value, such as a database's password, gets a new value in each preview that copies its service, so a database added on the canvas starts in the preview with nothing to set.

Open previews are listed under Open now in the panel, and in the environment switcher under the environment they start from. Each one is a branch of that environment, so you change, sync and close it like any other branch.

A preview's first deploy runs without your secrets, so code that needs a DATABASE_URL or an API key may fail until you set them. The Ployz · ready to merge check on the pull request lists them under Not set in pr-142, and each service's card on the preview's canvas reads like 1 not set.

Open the preview, open the service's Variables, and choose Set value on each. Then deploy the preview again, or push. A value you set here stays in the preview: the merge doesn't bring it to production.

Code reaches production through Git, and so do the preview's setting changes, like a new variable or a new service: when the pull request merges on GitHub, every change the preview made since it started lands in the environment that deploys the branch the pull request merges into. That is production, for a pull request into production's branch. Environments below it that deploy the same branch get the code, not the settings.

To see what will land, open the preview and click On merge · 3 at the top right of the canvas. The list reads #142 → production, one row per change: the service, the setting, then production's value → the preview's, like CACHE_TTL 30 → 60. In a row's ⋯ menu:

  • Edit sets the value production gets instead of the preview's. The row shows Edited and the preview's own value under it; Reset in the ⋯ menu goes back to the preview's.
  • Exclude keeps the change in the preview only. The row stays in the list, greyed, marked Excluded; click Include to put it back.

A setting production changed after the preview started reads production 45 → 60: the preview's value wins when it merges. A secret the preview added that production has no value for reads Not set in production. Set it in production, or with Edit, before you merge; otherwise production's deploy skips it, and any variable that references it, and warns. For a service that's new to production, set its sealed values after the merge. Removed variables and settings ride too. Replicas, CPU and memory limits, and custom domains never do.

A service or config the preview removed reads Removes db. If production changed it since the preview started, the row adds Changed there; the merge removes it anyway. If a production service still mounts a removed config, the row reads In use with what mounts it, and the merge leaves it in production while the rest lands. A reference never holds a removal: a variable in production that references db becomes a Broken reference once db is gone. A removed volume reads Kept: the merge never removes a volume or its data, and production's services keep their mounts on it unless the preview removed the service too. Remove it in production yourself when you're sure. Only what the preview copied can be removed this way; a service the preview never had stays in production untouched.

Ployz posts a Ployz · ready to merge check on the pull request that mirrors the list, like 3 config changes · TOKEN not set. It's green, or neutral when a secret is Not set, production changed the same setting, or a removal production still uses reads In use. It never fails, so it never blocks a merge. Its Details link opens the list. A pull request into a branch no Environment deploys from reads Nothing deploys from release: its changes stay in the preview.

When the pull request merges, production gets one saved version, Merged #142, and the merge commit's push deploys it with the code. To take it back, open its ⋮ in production's Versions and choose Undo these 3 changes.

The merge deploys every service it changed: one whose own settings changed, one that mounts a changed config, and one that reads a changed variable. It does so even for a service with auto-deploy off or one that doesn't build from the branch, which redeploys with the code it last built. An edit you staged in production but didn't save stays staged.

A removal deploys too: the service's containers stop and go away, and its volumes stay on the server with their data. The merge opens no approval, because it never deletes volume data. Undo in production's Versions brings the service or config back whole, and the next deploy starts it on the same volumes. Its secrets come back Not set: choose Set value on each before that deploy. If another service took its name since, Undo is refused with api exists. Rename it first.

If the merge couldn't land in production, or landed but couldn't deploy, the check says so, like Didn't land in production or Saved in production, not deployed, with the reason. A preview whose changes didn't land stays open, so nothing it held is lost.

To take the changes before the merge, click Sync · 3, check each change as for any sync, and click Sync 3 changes. They become production's changes to deploy now, and leave the On merge list. From the CLI, ployz env sync --to production from the preview does the same.

A preview you're not testing can come off your servers and keep its settings.

  1. Open the preview and open the Sync button's ▾ menu.
  2. Click Shut down until the next push. If it has data, type my-app/pr-142 to confirm. A preview with no data shuts down without asking.

Its services stop and its own data is deleted. Its settings, synced changes and pull request stay. The next push brings it back, once it deploys, or click Deploy pr-142. It starts fresh: its databases start empty and setup commands run again.

To delete it instead, open the ▾ menu, then Close pr-142…, type my-app/pr-142 and click Close branch. If the pull request is still open, its next push makes a new one.

Next: get ready for production.