Skip to content
Specific Docs
Esc
↑↓navigate↵open⌘Jpreview
HomeDashboardSupport
On this page

Preview environments

Temporary copies of an environment for testing changes with real data.

A preview environment is a temporary copy of an existing environment. By default, it runs the same services with their own URLs and their own network namespace, on top of its own copy of the parent’s stateful data, so a change can be tested end to end without touching the parent.

How previews are created

  • Per pull request - with the GitHub integration connected, Specific creates a preview environment for each open pull request, keeps it up to date as new commits are pushed, and posts its URL back on the PR. Connect GitHub from the dashboard.
  • Manually - deploy one on demand with specific deploy --preview.

Preview environments are ephemeral: pull-request previews are removed when the PR is closed or merged, and a preview can be given an expiry, after which Specific cleans it up automatically.

Run specific status to list every environment and its env_... ID, including preview environments. Target a preview with --environment on commands that take one.

Partial previews

For projects with several services, you can turn on Partial previews in the parent environment’s dashboard settings. New previews then deploy only the services affected by your changes and connect unchanged services to the parent environment.

This makes previews faster and uses fewer resources, but they are not fully isolated from the parent. Specific clones databases and buckets used by the affected services, while resources used only by unchanged services stay in the parent environment. If a change does not affect any service, Specific skips creating an empty preview.

What’s copied from the parent

A full preview branches off a parent environment and starts from its data. Each resource is forked in the way that’s fastest for that service:

  • Postgres databases are branched - an instant, copy-on-write branch.
  • Object storage buckets are forked.
  • Volumes are cloned - an instant, copy-on-write copy of the parent volume.

The preview gets its own isolated database, buckets, and volumes; writing to them never affects the parent. Partial previews clone only the resources used by services running in the preview.

A volume clone is an exact replica of the parent’s on-disk data (uploads, caches, and search indexes alike), so the preview’s service boots on it exactly as it would after a restart, with no extra configuration.

Secrets and config

A preview also inherits the parent environment’s secrets and config values, so its services start with the same configuration the parent runs with - nothing to re-enter.

To give previews a different value for a specific secret or config - say a sandbox API key or a test-only endpoint - set a preview override on the parent environment’s Secrets and config page in the dashboard. Every preview branched from that environment then uses the override for that value while still inheriting everything else. See Secrets and config.

Observability

Previews stream logs and metrics exactly like long-lived environments. Query them by targeting the preview with --environment:

specific query --environment preview-a1b2c3d4 \
  "SELECT Timestamp, Body FROM observability.logs ORDER BY Timestamp DESC LIMIT 50"

See Observability for the full query reference.

Was this page helpful?