Turn it on
Connect the app to a git repository first (see git integrations). Then:list with no app name shows previews across every app you can read.
Lifecycle
- Opened or reopened deploys a preview. A new push to the pull request redeploys it.
- Closed or merged tears it down, whether or not it merged.
- Teardown removes the preview app, its containers, its disposable databases, and its env overrides.
- Stale sweep tears down previews that have had no updates for their TTL. The default is 7 days. Set it per app with
--ttl-hours, or for the whole control plane with the runtime settingdeploy.preview_ttl_hours(levelrail-cli settings runtime set deploy.preview_ttl_hours 72, applies on the next sweep; 0 keeps the startup default) orAPP_PREVIEW_TTL(a Go duration such as168h). A per-app value wins. The sweeper runs every hour by default, set byAPP_PREVIEW_SWEEP_INTERVAL. - A preview stuck in deploying longer than
APP_PREVIEW_STUCK_AFTER(default 30 minutes) is marked failed by the startup sweep.
levelrail-cli apps previews open web 42 opens the preview’s URL in your browser (--print prints it instead).
teardown removes one pull request’s preview now. extend keeps one preview past its TTL. sweep removes every stale preview across all apps.
Limits
Two caps bound how many previews run at once:APP_PREVIEW_ENV_MAX_PER_APP(default 10) caps live previews per app.APP_PREVIEW_ENV_MAX_TOTAL(default 50) caps live previews on the control plane.
--max-previews, where 0 means the platform cap applies.
When a cap is full, the app’s on_limit decides what happens:
limit_reached and the reason.
Fork pull requests
By default a pull request from a fork is held. It does not deploy until someone approves it. Approve a held pull request once with:--share-secrets to give that one deploy the app’s environment variables and secrets. Without it, a fork preview gets no app environment.
To skip the hold for forks, set --allow-forks. Forks then deploy without approval but still get no app environment. Only --fork-secrets gives fork previews the app’s environment and secrets, so turn it on only if you accept that a fork’s code runs with them:
Database strategy
Each preview can get a database. The default isnone, which gives the preview no database.
The strategy applies to single-service apps. A multi-service app, or an app whose
app.yaml declares databases:, uses that file instead. Mark a database with ephemeralInPreviews: true there to give every preview its own copy.
Resources, idle sleep, and visibility
- Each preview gets 256Mi of memory and 0.25 CPU by default. Change them with
--memoryand--cpu. - A preview sleeps after 30 minutes without requests. Change it with
--idle-sleep-minutes, or for the control plane withAPP_PREVIEW_IDLE_SLEEP_MINUTES. - Search engines do not index preview URLs by default. Add
--allow-indexingto allow it. - Put basic auth in front of every preview of an app with
--gate, plus--gate-usernameand--gate-password. The password is write-only: it is stored, not shown again. The previews list shows a badge per preview with a domain: Basic auth on or Public, read from that preview’s owngatedflag. Against an older server without the flag, it falls back to the app setting (including Gate needs a password when the gate is on and no password is stored). The previews list API and the CLI table also carry a per-previewgatedflag (GATED column), true when that preview’s own domain currently sits behind basic auth or a sign-in gate. It is a flag only, never the credentials, and read-only users see it too.
levelrail-cli apps previews settings web with no policy flag to see the current values.
Pull request feedback
Previews can report back to GitHub: a commit status on each deploy, and one pull request comment that is updated in place. This is off by default and opts in per app:APP_GIT_STATUS_ENABLED=false.
Environment overrides for one pull request
Set a value for one pull request only, for example to point one preview at a staging API. The override takes precedence over the app’s environment for that pull request, and applies on its next deploy.list. Use --secret for anything sensitive.
Branch deploys
A branch deploy gives a branch a stable URL of its own. It is separate from pull request previews and rebuilds on every push to the branch.--modeisoff,all, orpatterns. Onlyallandpatternsgive branches a deploy. Inpatterns, a pattern is an exact branch name or a glob where*matches any characters, including/. The production branch never gets one.- A branch deploy is removed when the branch is deleted, or after 14 days with no push.
APP_BRANCH_DEPLOY_TTLchanges the idle time. APP_BRANCH_DEPLOY_MAX_PER_APP(default 10) caps live branch deploys per app. A push past the cap is ignored with a note.- Branch-scoped env overrides are set with
levelrail-cli apps branch-env.
Migration step and prebuilt images
Two optional settings per app, both off by default. They are set throughPUT /api/v1/apps/{name}/preview-policy (migrate_command, migrate_timeout_seconds, image_tag_template).
- Migration step.
migrate_command(for examplenpm run migrate) runs once throughsh -cinside the preview’s container, after the database strategy has been applied and before the preview is marked active. The container carries the preview’s environment. If the command exits non-zero or times out, the preview is marked failed and the masked output tail is the failure reason, shown in the preview list and the pull request comment. The timeout ismigrate_timeout_seconds, elseAPP_PREVIEW_MIGRATE_TIMEOUT(default 10 minutes). The wait for the container to be running isAPP_PREVIEW_MIGRATE_WAIT(default 2 minutes). It applies to single-service previews, not static or multi-service ones. With theseedstrategy the restore finishes first (bounded byAPP_PREVIEW_SEED_TIMEOUT), the command then runs in a container started after the database env was attached, and a seed that cannot run (no runner, no backup, low disk, restore error) fails the preview instead of migrating an empty database. If the migration or the seed fails, the preview’s own database is removed and the live app and its database are not touched. With thefreshstrategy the command waits until the new PostgreSQL database accepts connections (pg_isreadyinside its container, bounded by the migrate timeout) and the preview fails if it never does.freshwith another engine fails, since readiness cannot be checked. Thesharedstrategy (it would migrate the production database) anddatabases:inapp.yamlfail with a message saying so. Theseedandfreshpaths are built and tested with a fake runner, not proven against a live database. Set it from the CLI withapps previews settings <app> --migrate-command ... --migrate-timeout .... - Prebuilt image.
image_tag_templatedeploys a registry image for the pull request with no build, for exampleghcr.io/org/app:pr-{number}. Placeholders are{number},{sha},{short_sha}and{branch}, and at least one is required. Set it with--image-tag-template. Your CI must push that tag before the pull request event arrives, or the deploy fails. It applies to single-service previews.
Static site previews
When an app’s build type is static (single service), a preview publishes the pull request’s head commit as its own static site named<app>-pr-<number>. The live site, its route and its release history are not touched. Closing the pull request, the stale sweep and apps previews teardown remove the preview’s site row, route and files. The basic auth gate (--gate) is created and enforced on static previews the same way as on container previews. If the gate cannot be created (no username, no stored password, no master key), the preview is not published and is marked failed with the reason, rather than served publicly. A forward-auth gate on the preview’s domain is not enforced on static routes, so the preview is refused with a clear error instead. Built and tested, not proven on a real host.
Pull request comment commands
Comment commands are off until you turn them on per app, andAPP_PR_COMMENT_COMMANDS_DISABLED=true switches them off for the whole control plane:
The commenter must have
write or admin permission on the repository, checked against GitHub for each command and refused if the lookup fails. Comments from bots and GitHub Apps are ignored, each comment id runs once, and per-pull-request and per-user rate limits apply (APP_PR_COMMENT_COMMANDS_PER_PR_PER_MINUTE, APP_PR_COMMENT_COMMANDS_PER_USER_PER_MINUTE). The commands are GitHub only. There is no /destroy or /deploy command: teardown stays with closing the pull request or the CLI. Built and tested, not proven on a real host.
Not yet
- Migration step with
shared,app.yamldatabases or a non-PostgreSQLfreshdatabase.migrate_commandworks with thenoneandseedstrategies, and withfreshon PostgreSQL. With the others the preview fails with a message saying so. - Preview databases for branch deploys. Branch deploys are app-only. The branch deploy code path never creates, seeds or removes a database, so a branch deploy uses the app’s own database env. Database strategies apply to pull request previews only.
- Comment commands outside GitHub. GitLab, Gitea and Bitbucket pull requests do not accept comment commands.
Preview host templates
By default a preview is served on a generated host. To choose the pattern, set a host template and the domain it renders under:pr-12.example.com for pull request 12. {branch} (reduced to one DNS label) works too. The template must contain {number} or {branch}, and the domain must be one of the app’s own domains or a subdomain of one, so a template can never put a preview on a host the app does not own. The domain is checked again at deploy time; if it no longer matches, the preview falls back to the default host. Point a wildcard DNS record at the server for the domain, or let automatic DNS handle each host. An empty template clears the setting.