Preview environments

A preview is a short-lived deploy with its own URL and its own preview-owned managed resources. With previews on, each pull request deploys its branch to a preview URL, and each push updates that preview in place. An agent can also create one for a pushed remote branch, through the CLI or the HTTP API. floo tears a preview down when you delete it, close the PR, or its TTL expires. A preview never reuses floo-managed dev or prod Postgres credentials. When a preview has managed Postgres attached, floo creates a preview database branch for it.

Turn previews on

Previews are off until you turn them on. There are two controls, and the per-PR one wins.

The app default, in `floo.app.toml`

[github]
preview_environments = true
preview_ttl_hours = 72

Commit and push the config. The next PR webhook from GitHub creates or refreshes a preview. preview_ttl_hours sets how long a preview stays up after it is created or refreshed by a push; the default is 72, and traffic does not extend it. Closing or merging the PR tears it down sooner. A missing preview_environments key means previews are off; preview_environments = false turns them off for future PRs.

[preview] enabled and [preview] ttl_hours are deprecated aliases for these keys. They work for one migration window, and each deploy that uses them emits a legacy_preview_toml warning. Move the values into [github] and delete them from [preview]. [preview.data] is unaffected and remains the hydration surface.

The per-PR override, from a pull request comment

Comment on a pull request to override the app default for that PR:

/floo preview on

The preview deploys within a normal deploy cycle, without another commit. To turn a preview off for one PR when the app default is on:

/floo preview off

The rules:

Rule	Detail
Accepted words	`on` or `enable`; `off`, `disable`, or `skip`. Case-insensitive.
The comment must contain only the command	`/floo preview on` works. `let's take a look, /floo preview on` does not. Put the command in its own comment.
Who can run it	Repository owners, members, and collaborators. Comments from outside contributors are ignored.
Which comment wins	The most recently updated authorized command on the PR.
Undoing it	Edit or delete the command comment. floo re-reads the remaining comments: an older authorized command still applies, and with none left the PR returns to the app default.
Fork PRs	The app default does not apply. A fork PR gets a preview only from an `on` command by a user with push access.

When most PRs on a repo do not need a preview, leave preview_environments = false and opt in the PRs that want a live URL. When the app default is on, /floo preview off skips a noisy PR. If the PR is already closed or merged when the command lands, floo tears the preview down instead of deploying one.

Create a sandbox from the CLI

floo previews up creates an isolated sandbox for a feature branch without waiting on a pull request preview:

git push origin feat/foo
floo previews up --app my-app --branch feat/foo --wait

It deploys GitHub source only, never local dirty files or an archive of your checkout, so push the branch or pass a remote ref first. Lifecycle commands:

floo previews list --app my-app
floo previews status --app my-app feat/foo
floo previews logs --app my-app feat/foo --follow
floo previews delete --app my-app feat/foo --yes

The preview argument can be the exact slug, a preview URL, the source branch, or #123 when that PR number resolves to one preview. Add --json for stable output:

floo previews up --app my-app --branch feat/foo --wait --json

JSON output includes the app, preview slug, source_branch, deploy_id, status, URL, expiry, database_branches, and dev_prod_untouched: true. --wait exits non-zero when the deploy fails. Managed-resource isolation failures surface as PREVIEW_MANAGED_SERVICE_ISOLATION_UNAVAILABLE; fix the attached managed service state and retry after pushing a new commit or rerunning the command. Deleting a preview sandbox tears down only preview-owned services, managed resources, gateway routes, and env vars. Dev and prod resources are untouched.

Preview database branches

A preview database branch is preview-owned managed Postgres state, isolated from dev, prod, and other previews. Migrations, reviewer changes, and agent experiments land in that branch only. empty and seed start from a blank database; clone-dev starts from a copy of dev. Inspect the branch behind a preview:

floo previews resources list feat-db-abcde --app my-app
floo previews resources show feat-db-abcde --app my-app --resource postgres:default

The preview argument takes the same forms as floo previews. Add --json for stable fields:

floo previews resources list feat-db-abcde --app my-app --json

list JSON includes the app, preview context, and managed_resource_branches; show returns one managed_resource_branch. Each branch reports its type, resource_key, source_env, hydration_mode, resource_status, reset eligibility, and expiry. These commands include Postgres, Redis, and Storage and never return plaintext credentials.

Reset Redis and Storage preview branches

Use floo previews resources reset for Redis and Storage branches:

floo previews resources reset feat-db-abcde --app my-app --resource redis:default --yes

Redis reset flushes only the preview Redis database. Storage reset deletes only live objects inside the preview bucket and keeps the bucket name and its STORAGE_BUCKET value stable, so running preview revisions keep working. Both then reapply the preview data policy. Reset is blocked when the preview has no matching managed attachment, when the branch is not ready, when a deploy is in flight for that preview, or when the data belongs to dev, prod, or an external resource.

Choose preview data

Use [preview.data] to choose how a new preview branch starts.

Empty

empty is the default. floo creates a fresh preview database branch with a blank database, so migrations run from scratch.

[preview.data]
mode = "empty"

Use this for apps that can boot from migrations alone.

Seed

seed runs your seed command once after migrations and before the preview is marked live.

[preview.data]
mode = "seed"
seed_command = "bin/rails db:seed"

The command runs in a preview-scoped one-off job with preview env vars. Pushing another commit to the same PR reuses the preview data unless you change the preview data policy.

Clone dev

clone-dev copies dev data from every attached managed resource into its preview branch.

[preview.data]
mode = "clone-dev"

Use it when a reviewer needs realistic dev data without touching the dev resources.

Resource	What is copied	Limits
Postgres	Dev database data into the preview database, before migrations run	None
Redis	Strings, hashes, lists, sets, sorted sets, and streams, with TTLs preserved where Redis reports them	1,000 keys · 10,000 entries per key · 100,000 entries total · 1 MB per string value
Storage	Dev bucket objects into the preview bucket, by server-side copy	100,000 objects · 10 GiB

The Redis clone runs its preflight before flushing the preview database, so an unsupported key type or an oversized keyspace fails closed and leaves the preview as it was. Hydration runs at most once per policy, so another push to the same PR keeps reviewer-created state. Change the policy and the next deploy hydrates again.

Unsupported modes

floo does not support:

Raw prod clone.
Sanitized prod clone until the admin-gated runner exists.
Merging preview branch changes back into dev or prod.
Instant copy-on-write branches from arbitrary points in time. Storage copy is explicit object copy, not provider-native branching.

If a config asks for unsupported data behavior, floo fails closed instead of silently using dev or prod credentials.

Multi-service apps

Preview branches follow the same managed credential attachment rules as dev and prod. Attach managed Postgres only to the services that need it:

[services.api.env]
managed = ["postgres"]

[services.web.env]
managed = []

If no service declares managed, legacy apps receive managed credentials in every service. Once any service declares managed, omitted services receive none.

Troubleshooting

Symptom	Meaning	What to do
No preview appears for a pull request	Previews are off for the app and no authorized `/floo preview on` command exists on the PR	Set `[github] preview_environments = true` in `floo.app.toml`, or comment `/floo preview on` on the PR
A `/floo preview on` comment did nothing	The comment carried extra text, or its author is not a repository owner, member, or collaborator	Post the command in its own comment with nothing else in it, from an account with repo access
`floo previews resources list` shows no branches	The preview has no floo-managed service attachments	Declare `[managed.default] type = "postgres"`, attach it with `managed = ["postgres"]`, and push the config
Reset is blocked	The branch is not ready, is not preview-owned, or the preview has a deploy in flight	Re-run `floo previews resources show ... --json` and inspect `reset_blocked_reason`
Preview creation fails before deploy	floo could not provision isolated managed resources	Fix the managed-service state and push another commit
`clone-dev` fails on Redis	An unsupported key type, or a keyspace past the clone limits	The preview Redis database is left untouched. Trim the dev keyspace, or use `empty` or `seed` for that preview
`clone-dev` fails on Storage	The dev bucket is past 100,000 objects or 10 GiB	Use `empty` or `seed` for that preview

Get started

Build with your stack

Deploy

Managed services

Environments

Operate

Access

For agents

Preview environments

Turn previews on

The app default, in `floo.app.toml`

The per-PR override, from a pull request comment

Create a sandbox from the CLI

Preview database branches

Reset Redis and Storage preview branches

Choose preview data

Empty

Seed

Clone dev

Unsupported modes

Multi-service apps

Troubleshooting

​Turn previews on

​The app default, in floo.app.toml

​The per-PR override, from a pull request comment

​Create a sandbox from the CLI

​Preview database branches

​Reset Redis and Storage preview branches

​Choose preview data

​Empty

​Seed

​Clone dev

​Unsupported modes

​Multi-service apps

​Troubleshooting

​Related

Turn previews on

The app default, in `floo.app.toml`

The per-PR override, from a pull request comment

Create a sandbox from the CLI

Preview database branches

Reset Redis and Storage preview branches

Choose preview data

Empty

Seed

Clone dev

Unsupported modes

Multi-service apps

Troubleshooting

Related