Preview environments
Give every pull request its own isolated Databricks deployment, wired through the generated CI pipeline.
Runway treats preview as a first-class deployment environment. Every pull request can get its own isolated Databricks deployment so reviewers see the change running, not just a diff.
How a preview differs from dev and prod
| dev | preview | prod | |
|---|---|---|---|
| Requested by | fr deploy | fr deploy --preview --pr <n> | trusted worker only |
| Requires a PR number | no | yes (enforced at schema) | n/a |
| Runs the release gate | yes | no (fast feedback) | gate already passed |
| Direct request allowed | yes | yes | no — must be promoted |
A preview deploy requires a prNumber; a preview request without one is rejected at the
schema stage. Preview deploys intentionally skip the quality gate so reviewers get a running
environment quickly — the gate is what protects the promotion path to prod, not the preview.
The generated CI pipeline
fr init writes .github/workflows/deploy.yml, already wired to Runway:
- On
pull_request:fr deploy --preview --pr <number>— a per-PR preview environment. - On pull-request close:
fr preview destroy --pr <number>— governed teardown of that PR's bundle resources followed by asynchronous deletion of its Lakebase branch. - On push to
main:fr deploy --version <sha>— a dev deploy that also requests the gate.
Set the RUNWAY_API_URL and RUNWAY_ORG repository variables so the workflow targets your
control plane and organization.
Exact ownership
Runway creates runway-<tenant>-<app>-pr-N (hashed only when required by the 63-character
Lakebase limit) from the configured production branch. It passes the full branch and primary
endpoint names as BUNDLE_VAR_lakebase_branch and BUNDLE_VAR_lakebase_endpoint.
BUNDLE_VAR_preview_suffix=-pr-N still isolates Apps, bundle roots, secret scopes, Unity Catalog,
and every resource outside Lakebase. A database branch never replaces those namespaces.
Branch lifecycle and failure behavior
The Databricks edge creates or verifies the branch before bundle validation. Reconciliation does the same, so a retry never silently deploys against an expired branch. Reusing an existing branch is allowed only when its recorded source is the configured source branch. A name collision with a different source fails closed.
Preview branches receive a 24-hour TTL by default (configurable from one hour to 30 days). Normal
teardown destroys the bundle first, requests branch deletion, and polls until Databricks reports the
branch absent. A timeout or permission failure leaves the action failed and auditable; the TTL limits
residue after an interrupted create. Creation and deletion require CAN MANAGE on the Lakebase
project. Branch deletion is permanent and Databricks will reject it while child branches remain.
This is implemented and mock-proven. Promote it to live-proven only after the retained workspace
suite creates, uses, and destroys the branch on the exact release artifact.
Databricks delivery
Immutable Unity Catalog Volume artifacts, digest verification, Asset Bundles, and Databricks Apps — how Runway ships to a workspace.
Environment Variables
How Runway offers Vercel-style environment configuration on Databricks secret scopes without ever putting a value in an action, event, or projection.