# Preview environments > Give every pull request a temporary copy of your app at its own https address. For agents: [llms.txt](https://ployz.dev/llms.txt) indexes the Ployz docs as Markdown. 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. ## Turn on preview environments Previews work for services that [deploy from GitHub](https://ployz.dev/docs/deploy/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](https://ployz.dev/docs/deploy/github) 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. > [!WARNING] > A service you don't copy, usually a database, is shared with production and shows > **production's** in amber with a warning sign. Every pull request's code reads and writes that data. Click it and choose > **Separate postgres** unless that's what you want. 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. ## Who deploys automatically 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 Servers with [device enforcement](https://ployz.dev/docs/servers/manage-servers#require-a-devices-signature-for-restarts-and-joins) on open a preview only under a preview rule you approve from an approved device. It works like [deploy on push](https://ployz.dev/docs/deploy/github#deploy-on-push-to-servers-that-enforce-device-approval): 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: ```bash 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: ```text Approving previews of production: repository acme/web, parent branch main builder getployz/build/.github/workflows/build.yml@39e1f488e492c0641e520777e481e8f5b266985b urls -pv-.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-.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](#review-a-preview-from-a-fork). 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](#review-a-preview-from-a-fork). It's the same file as for [automatic deploys](https://ployz.dev/docs/deploy/github#deploy-on-push-to-servers-that-enforce-device-approval). **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: ```yaml 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. ### Review a preview from a fork 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: ```text 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. ## What each pull request gets 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](#who-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](#set-a-previews-secrets). - A [generated value](https://ployz.dev/docs/services/variables#generate-a-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](https://ployz.dev/docs/environments/environments) of that environment, so you change, sync and close it like any other branch. ## Set a preview's secrets 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. ## Config changes in a pull request 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](https://ployz.dev/docs/environments/environments#sync-the-change-to-production), 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. ## Shut down a preview 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](#who-deploys-automatically), 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](https://ployz.dev/docs/production-checklist).