For the complete documentation index, see llms.txt. This page is also available as Markdown.

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_KEY

The 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:

Method
Who builds the environment
Use it when

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

Field
Type
Required
Description

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

Preview anatomy: inputs, the preview container, and what consumes it
How the YAML fields translate to a running preview

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.

Field
Type
Required
Description

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.

Field
Type
Required
Description

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?