Previews

With previews on, every pull request gets a full copy of the project with its own environment, URLs and databases. The preview deploys the pull request's head commit and updates on every push to it. When the pull request is merged or closed, the preview is removed.

Turn previews onCopy Anchor Link

Previews are off for a new project. Open the project's Settings → Previews and switch on Preview environments. The same page sets which pull requests get a preview:

A pull request with [skip preview], [preview skip] or [no preview] in its title gets no preview. Previews need a pull request event from GitHub, GitLab, Gitea or Forgejo. Repositories connected as a plain git server don't send one.

How a preview is createdCopy Anchor Link

When a pull request opens, launchroom:

1. Creates an environment named pr-<number> ("PR #128") as a copy of the base environment, with its own private network.
2. Applies the variables targeted at previews and at the pull request's branch (see Variables).
3. Starts the databases and other image-based services first and prepares their data.
4. Deploys the apps at the pull request's head commit.

Each new push to the pull request deploys its new head commit. Previews are listed on the project's Previews tab and under their own heading in the environment switcher. Open one to see its canvas with the pull request on top.

Focused previews: when services have watch paths, launchroom builds only the services whose files the pull request changed. The rest run the commit the base environment runs and reuse their existing image without a build. The preview still has every service.

Limits: by default, previews run 1 replica per service and at most half a CPU per replica (memory as in the base). They are placed only on servers with Previews allowed in their placement settings. See Roles and placement.

Databases in previewsCopy Anchor Link

Set what a preview gets for each database under Databases in previews on the same settings page:

The seed command lives in the app's Deploy settings (for example php artisan db:seed or npx prisma db seed), as a list of arguments.

Copies have a size limit. The source's latest backup must be under the team's limit (1 GB by default, shown on the page). A database without a backup can't be the source. Copying or sharing production data needs Allow production data under Access, which only owners and admins can switch on. Caches and other volumes always start empty.

URLsCopy Anchor Link

Every web service in a preview gets:

• its preview address, {service}-pr-{number}.{project}.{your apps domain}
• a branch address, {service}-git-{branch}.{project}.{your apps domain}, which redirects to the current preview address
• an immutable address per deployment, {service}-{id}.{project}.{your apps domain}, which points at that version while it runs

Preview hosts send X-Robots-Tag: noindex, so search engines don't index them. Without a platform domain the addresses use the sslip.io fallback (see Domains and TLS).

Protection and share linksCopy Anchor Link

Require a login is on by default. Team members open a preview after signing in to launchroom. Everyone else needs a share link. The sign-in sets a cookie for the preview's host only and doesn't touch your dashboard session.

• Share link: on the Previews tab, create a link for someone outside the team. The link is valid for up to 30 days, can be revoked at any time and stops working when the preview is removed.
• Automated tests: generate a Bypass secret under Automated tests and send it as the X-Launchroom-Bypass header from CI. The header is removed before the request reaches your app. The secret is shown once.

Pull requests from forksCopy Anchor Link

Code from a fork can do anything your build and app can do, so fork pull requests get No previews by default. Choose After your approval under Pull requests from forks to allow them:

• Authors with write access to the repository get previews automatically.
• For everyone else, the preview waits on the Previews tab until a team member who can deploy presses Approve, or someone with write access adds the preview label.
• An approval covers only the commit you reviewed. New commits wait for approval again while the approved one keeps running.

A fork preview never gets the base's data or secrets:

• Every secret not set on the preview itself is empty.
• Databases are always new and empty. Copy and share are turned into new and empty, and the page says so.
• A launchroom.json in the pull request can't add services, volumes or connections.

See launchroom.json.

Status on the pull requestCopy Anchor Link

launchroom reports back to the pull request with one comment that lists every service with its status and URL. The comment is updated in place on each push:

CleanupCopy Anchor Link

A preview is removed when its pull request is merged or closed, after the inactivity period, or when a filter stops matching (for example the required label is removed). A daily sweep also removes previews whose close event never arrived. Removing a preview stops its services, frees its slot for the next one in the queue and removes its routes. Its volumes stay on the servers for 7 days before they are deleted. Reopening the pull request starts a fresh preview.

Next stepsCopy Anchor Link