Blossom Docs
Blossom

Apps

Preview Environments

Full copies of an Environment, database included, for every branch or pull request

3 min read

A Preview is a full copy of an Environment on another branch, with its own URL and its own database. Use it to try a change for real before it reaches staging or production. For a quick start, see Preview Every Pull Request.

Create Previews

Create How
By hand New Preview on the Previews page
For every pull request Pull requests into in Preview Settings
For matching branches Branches matching a pattern such as preview/*

Select one or both triggers in Preview Settings, then save to enable automatic Previews.

From the CLI, create one by hand with:

blossom environment:preview:create --id ENVIRONMENT_ID --branch checkout-redesign -f

Automatic Previews need the repository connected through GitHub, GitLab or Bitbucket. Each push to a branch deploys its Preview. A closed or merged pull request, or a deleted branch, deletes it. On GitHub, Blossom comments on the pull request with the Preview’s URL and who can open it. Pull requests from forks never get a Preview, so outside code never runs with your variables.

What A Preview Shares

Each deploy takes the Environment’s current Services, build settings, deploy hooks and variables, so a change there reaches every Preview on its next deploy. A Preview keeps its own:

  • URL: a generated one; custom domains stay with the Environment
  • Database: its own PostgreSQL database when the Environment links one
  • Variables: overrides for Previews only, such as a sandbox payment key
  • Access: Account members by default, with its own share links

Override a variable for one Preview:

blossom env_var:push --environment PREVIEW_ID --file .env.preview

Databases

When the Environment links PostgreSQL, each Preview gets its own database, linked under the same variable, usually DATABASE_URL. It starts empty, and two settings fill it:

  • Setup command: runs once before a new Preview’s first release, such as bin/rails db:prepare db:seed.

  • Preview data: a sample database every new Preview starts from. Upload a PostgreSQL custom archive of up to 250 MB:

    pg_dump --format=custom --no-owner --no-privileges --file sample.dump SAMPLE_DATABASE
blossom environment:preview:data:upload --environment ENVIRONMENT_ID --file sample.dump

Use sample data, not a copy of production, since share links can open a Preview to people outside your Account.

Preview Settings

Previews → Settings controls every Preview of the Environment:

  • Container size: Micro by default, or Small, Medium, Large, or each Service’s own size. Small containers keep Previews light on resources.
  • Delete after: 1, 3, 7 (the default), 14 or 30 days without a deploy, so a forgotten Preview frees its resources
  • Maximum Previews: 5, 10 (the default), 20 or 50
  • Access: Account members, or the same as the Environment

From the CLI, environment:preview:settings:init writes the same settings to edit, and environment:preview:settings:update saves them.

Delete Previews

Previews delete themselves when their pull request closes or they go unused. To delete them yourself:

blossom environment:delete --id PREVIEW_ID --yes -f
blossom environment:preview:delete_all --environment ENVIRONMENT_ID --yes

Requirements

  • Previews work for Environments that deploy from a Git repository, without Persistent Services.
  • Preview databases are PostgreSQL.
On this page