Preview YAML
This page documents the preview block of your Verify configuration, edited in the Aviator dashboard under Verify → Settings → Verify (with the repo selected). For the concept of what a preview is and how it fits in, see Concepts: Previews.
Shape
preview is a list nested under the top-level verify key. Each entry defines one preview.
verify:
preview:
- name: default
image: api-preview
port: 8000
setup: .aviator/scripts/preview-setup.sh
secrets:
- DB_PASSWORD
- STRIPE_KEYThe verify: wrapper is required — the schema rejects unknown top-level keys, so a bare preview: block fails validation.
If a single preview is declared with no name, it's treated as default. Always set names explicitly when you have more than one.
Preview methods
Every entry has a method that decides who owns the environment:
sandbox (default)
Aviator boots a container from a registered preview image and runs your setup script.
You want Aviator to own the environment end to end.
endpoint
Your CI builds and deploys the environment, then registers its URL with Aviator.
You already deploy a per-PR environment, or the environment needs infrastructure Aviator can't host.
method is optional and defaults to sandbox, so a config written without it keeps behaving exactly as before. The sections below document the sandbox fields; for the endpoint schema, see Endpoint previews.
A repo may declare any number of sandbox previews and at most one endpoint preview. When both kinds are present, the endpoint preview governs verification runs regardless of its position in the list; sandbox previews remain available to launch by hand.
Sandbox fields
name
string
no
Unique name within the repo. Defaults to default. Scenarios target a preview by this name.
method
string
no
sandbox or endpoint. Defaults to sandbox.
image
string
yes
Name of a preview image. Aviator caches the image locally and boots a container from it per run.
port
int
yes
Port the app serves on. Aviator handles exposing this as a public URL.
setup
string
no
Path (in the repo) to a setup script. Defaults to .aviator/scripts/preview-setup.sh. Runs after the container starts.
teardown
string
no
Optional path (in the repo) to a teardown script. Runs before the container is destroyed.
secrets
list of strings
no
Account secret keys. Each is injected into the container as an environment variable of the same name.
verify_skill
string
no
Repo-relative path to this preview's Verify skill entry point. Overrides the default .aviator/verify/skills/<preview-name>.md lookup.
Image
image is the name of a preview image registered with Aviator for your account. Aviator caches the image locally and boots a container from it for each verification run.
You can register an image through Settings → Sandbox in the Aviator UI. The same image system backs both the preview environment and the coding sandbox — set both to the same image when you want them to share dependencies and tooling.
Secrets
secrets is a list of secret keys defined on your account. Each name resolves to a value at boot time and is injected into the container as an environment variable of the same name:
Secrets are managed in the Aviator UI under Settings → Secrets. Scoped per account, granted to repos explicitly. The preview container never sees the unresolved name — only the value.
Verify skill
By default, Verify reads this preview's app-driving guidance from .aviator/verify/skills/<preview-name>.md (the entry-point file may reference other files in the repo). To point the preview at a file elsewhere, set a single path:
The path is repo-relative; when set, it replaces the default <preview-name>.md lookup. See Writing a Verify skill.
Setup script
setup runs inside the container after start. Use it for things that aren't baked into the image:
Two rules:
Idempotent. The script runs every time the preview boots. Don't assume a clean slate elsewhere.
Fast. Heavy work (large fixtures, dependency installs) should be baked into the image. Setup-time work is part of every run's latency.
See Managing previews for the bake-vs-setup tradeoff.
Teardown script
teardown is optional. When provided, it runs before the container is destroyed. Use it to release external resources the preview acquired (e.g. a per-run tenant in a shared test environment).
Anatomy
Sandbox examples
Minimal:
Multi-preview repo:
Endpoint previews (method: endpoint)
An endpoint preview is hosted outside Aviator. Your CI pipeline builds and deploys the environment for the pull request and registers its URL with Aviator; Aviator correlates that registration to the verification session, waits for it when a run needs it, drives it, and honors its expiry. It never builds or tears the environment down.
name
string
no
Unique name within the repo. Defaults to default. Scenarios target a preview by this name.
method
string
yes
Must be endpoint.
wait_timeout_sec
int
no
How long a verification run waits for a registered preview before falling back to code analysis. Defaults to 1800. Range 60–7200.
expires_default_sec
int
no
How long a registration stays current when it doesn't supply its own expires_at. Defaults to 7200. Range 300–86400.
verify_skill
string
no
Repo-relative path to this preview's Verify skill entry point. Overrides the default .aviator/verify/skills/<preview-name>.md lookup.
provision
object
no
How Aviator asks your system to build a preview for a commit, and tells it when the preview is no longer needed. Leave unset when your CI deploys on every push and registers on its own. See Provision.
Endpoint entries take none of the sandbox fields — image, port, setup, teardown, and secrets are all rejected, because the environment isn't Aviator's to build. Credentials for driving the app come from the registration itself.
Registering a preview is an API call from your CI pipeline. See Registering an external preview for the request shape, the waiting behavior, and the expiry and deregistration semantics.
Provision
With provision set, a verification run that needs the preview and finds nothing registered for its commit sends a preview_provision event, and sends preview_done when nothing will drive that preview any more. Aviator retires the commit's registration when it says done, so the next run asks again. type picks the transport.
type
string
yes
workflow dispatches a GitHub Actions workflow in this repo (workflow_dispatch); the event arrives in the workflow's inputs. webhook posts the event to the Verify webhook URL configured for your account under Settings → Integrations, signed with its secret.
workflow
string
workflow only
Filename of the workflow under .github/workflows/, with or without that prefix. Must be a .yml or .yaml file that declares a workflow_dispatch trigger.
ref
string
no (workflow only)
Which copy of the workflow file runs: branch (default) runs the file as it exists on the PR branch; default_branch runs the one on the repository's default branch.
type: webhook takes no further fields; the Integrations webhook URL only has to be set. See Provisioning a preview on request for the event payloads and what the receiver does with them.
See also
Last updated
Was this helpful?
