Early access is open. Stagd is free during the beta. Sign up
Reference

stagd.yaml

Every setting in stagd.yaml, what it takes and what it defaults to.

stagd.yaml (or .stagd.yaml) sits at the root of your repository. It’s optional: without it, Stagd reads your compose file and its labels. Stagd reads it at the commit it previews, so a pull request can change its own preview. Describe your app walks through it; this page lists every setting.

# yaml-language-server: $schema=https://stagd.dev/schema/stagd.schema.json
version: 1
app:
  compose: deploy/compose.preview.yaml
ingress:
  site: { service: web, port: 3000, primary: true }
  api: { service: api, port: 8080 }
build:
  web: { context: ., target: prod }
  api: { image: "ghcr.io/acme/api:sha-${STAGD_SHA}" }
env:
  APP_URL: ${STAGD_URL_SITE}
services:
  mail: {}
  postgres:
    seed: app-anonymized
    extensions: [vector, pg_trgm]
wait:
  checks: [build-images]
previews: on-demand
comment: Sign in as `demo@acme.test` with code 123456.
lifecycle: { sleep_after: 2h, expire_after: 36h }

The comment on the first line lets editors that understand JSON Schema (VS Code with the YAML extension, JetBrains IDEs) complete and check the file as you type. Check it from the command line with stagd validate, which reads it as previews will; stagd validate --explain also prints it as it reads, every default filled in.

Durations are written like 45m, 2h or 1h30m. Values in env, build and seed URLs can use variables and your org’s secrets: ${NAME}.

Top level

Setting Takes
version 1 The file’s format. Required
app app Where the app is described
ingress map of ingresses The preview’s URLs. When set, the compose file’s dev.stagd.* labels are ignored
build map of builds Where each service’s image comes from, by the compose file’s service name
services services What Stagd runs next to your app: mail capture, text messages, tracing, databases
env map of strings Variables the compose file can use, like compose’s .env file. A secret wins over a variable of the same name
database database A database outside the preview: a Neon branch per preview
previews previews When pull requests get previews. on-demand by default
comment Markdown, up to 4000 bytes Added to Stagd’s pull request comment once the preview is live, e.g. how to sign in
commands commands What happens to /stagd comments
wait wait GitHub checks that must pass before a commit deploys
registries map of registries Logins for pulling private images, by the registry’s host
lifecycle lifecycle How long previews stay awake and live, instead of your org’s setting
compute string The compute connection previews run on, by its name on Settings → Compute. Your org’s default when left out
testers map of testers Users Stagd signs in as on the preview, by name
sign_in map of sign-ins How your app signs people in, by name

Who may open previews isn’t here: a pull request mustn’t be able to open up its own preview. Set it in Stagd with stagd preview policy.

app

Setting Takes
compose path The compose file, from the repository’s root. Left out: compose.yaml, compose.yml, docker-compose.yaml or docker-compose.yml at the root

ingress

Each key is the URL’s name: lower-case letters, digits and dashes. The preview’s URLs are https://<name>--<preview>.stagd.run, and the primary one https://<preview>.stagd.run.

Setting Takes
service the compose file’s service Required
port 1–65535 The port the service listens on. Required
primary true The URL the pull request comment and the dashboard link to. Needed when there are several

build

Each key is a service in the compose file. Give context to build the image, or image to use one built elsewhere.

Setting Takes
context path Build from this directory, e.g. . or services/api
dockerfile path With context: the Dockerfile, from the context. Dockerfile by default
target stage With context: the Dockerfile’s stage to build
args map of strings With context: build arguments
image image reference Pull this image as it is, e.g. ghcr.io/acme/api:sha-${STAGD_SHA}, pushed by your CI
wait duration, 1m to 2h With image: keep trying to pull it for this long, for CI that pushes it after the deploy starts. Left out, a missing image fails the deploy at once

services

Each is off unless listed. {} turns one on with its defaults; false leaves it off.

Service
mail Catches the mail your app sends, over SMTP or through Resend’s or Amazon SES’s API, for the preview’s Mail tab. See mail and sms
sms Catches the text messages your app sends through Amazon SNS, for the preview’s Messages tab. See mail and sms
otel An OpenTelemetry endpoint and a trace viewer. Your services get OTEL_EXPORTER_OTLP_ENDPOINT, OTEL_SERVICE_NAME and the rest. See otel, and Traces in previews to make your app send
postgres A Postgres database. See databases
mysql beta A MySQL database
mariadb beta A MariaDB database
mongodb beta A MongoDB database (mongo works too)
azure_blob beta A fork of your Azure Blob Storage containers: your app reads their files, and what it writes stays in the preview. See azure_blob and s3
s3 beta A fork of your S3 buckets, as azure_blob is. See azure_blob and s3

Only your app’s own services get these variables and wait for these services: those with a build: in the compose file, or listed under build here (with context or image). A compose service with only image: is a stock image and is left alone. A value your compose file sets for one of these variables wins over Stagd’s; a bare DATABASE_URL:, which takes what the environment has, gets Stagd’s. Another of the service’s values can name one, to give it under the name your app reads: SQL_URL: ${DATABASE_URL}.

mail and sms

mail points every way of sending mail Stagd catches at the preview’s inbox, Mailpit; sms points Amazon SNS at the preview’s Messages tab. Neither needs settings.

Setting Takes
mail.catch list of names Only these ways are caught, e.g. [smtp]; the rest reach the real vendor. Left out, every way is, those added later too
Way Your services get, when it’s caught
smtp SMTP_HOST, SMTP_PORT, SMTP_URL, MAIL_HOST, EMAIL_HOST
resend RESEND_BASE_URL, RESEND_API_URL
ses AWS_ENDPOINT_URL_SES, AWS_ENDPOINT_URL_SESV2
sms AWS_ENDPOINT_URL_SNS

stagd-mock runs only when a way needs it, so mail: { catch: [smtp] } is Mailpit alone. mail.skip, which catch replaces, still works: the ways left alone.

otel

Your app sends traces only once it has an OpenTelemetry SDK started: Traces in previews has the steps for Node.js, Python, Go and Java.

Setting Takes
ignore list of paths Request paths whose traces aren’t kept; a * matches the rest, e.g. [/healthz, /internal/*]
export.endpoint URL Also send what the app sends to your own OTLP backend (Dash0, Honeycomb, Grafana Cloud)
export.protocol http/protobuf or grpc http/protobuf by default
export.headers map of strings Sent with it, e.g. Authorization: "Bearer ${DASH0_TOKEN}"

Databases

Stagd runs the database on a volume of its own and gives the services built from your repository its URL. They wait for it before they start.

Setting Takes
version a version, in quotes See the table below
database lower-case letters, digits and _ The database your app uses: postgres for Postgres, preview for the others
seed a seed’s name, or an https URL A dump restored once, when the preview is made: a seed on the Seeds page (or from stagd seeds), or a URL, which may use variables and secrets. Compressed with gzip, zstd, xz or bzip2, or not
extensions list of names Postgres only. See Postgres extensions
Database Versions Your app gets A seed is
postgres 16, 17, 18, 19 DATABASE_URL pg_dump: SQL, custom or tar format
mysql 8.4, 9 MYSQL_URL, DATABASE_URL SQL from mysqldump
mariadb 11.4, 11.8 MYSQL_URL, DATABASE_URL SQL from mariadb-dump or mysqldump
mongodb 7.0, 8.0 MONGODB_URI, MONGO_URL mongodump --archive

The default version is in bold. With two databases, the first in this table keeps DATABASE_URL. New commits and sleep keep the data.

Postgres extensions

services:
  postgres:
    extensions: [vector, postgis, pg_cron, pg_trgm]

Names are the ones CREATE EXTENSION takes. Each is made in the database when it’s created, before the seed restores, so a dump that uses one restores whole.

Kind Examples What Stagd does
Postgres’s own (contrib) pg_trgm, pgcrypto, uuid-ossp, citext, hstore, btree_gin, pg_stat_statements Nothing to install: they come with Postgres
Packaged by the PostgreSQL apt repository vector (pgvector), postgis and its family, pg_cron, timescaledb, h3, hypopg, pg_partman, pgaudit, pgrouting, age Runs the official Debian image of your version and installs them as the database starts, in seconds
Loaded at start pg_cron, pg_stat_statements, pg_stat_kcache, pg_squeeze, pgaudit, timescaledb Added to shared_preload_libraries. pg_cron runs its jobs in your database
  • A name with no package stops the database from starting, and its log says which packages Stagd looked for.
  • Added later: extensions are made when the database is new. On a preview that already has its data they’re installed, and your app’s own CREATE EXTENSION makes them. The first one that needs installing also moves the database from Postgres’s Alpine image to Debian’s, which sort text differently: destroy the preview to start it over.
  • Not packaged: run Postgres in your compose file with an image that has the extension.

azure_blob and s3

services:
  azure_blob:
    from: [lab-files, lab-images]
  s3:
    from: [lab-uploads]

Each runs blobfork in the preview: a copy-on-write fork of the containers or buckets your integrations name, as a database branch is of a database. Your app reads every file of the real ones; what it writes, overwrites and deletes stays in the preview, and the real ones never change. Nothing is copied up front.

Setting Takes
from list of integration names Your org’s Azure Blob Storage integrations (for azure_blob) or S3 integrations (for s3), as on Settings → Integrations. Each container or bucket keeps its own name in the fork
Service Your app gets
azure_blob AZURE_STORAGE_CONNECTION_STRING At the preview’s blob--<host> address, so SAS URLs your app hands a browser work too
s3 AWS_ENDPOINT_URL_S3, and AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY and AWS_REGION unless it sets its own At the preview’s bucket--<host> address, so presigned URLs work in a browser too. Its S3 client needs path-style addressing (forcePathStyle)
  • Your app’s own setting: a value your compose file sets wins. An app that reads another name, such as AZ_BLOBSTORE_URL, takes Stagd’s in its compose file: AZ_BLOBSTORE_URL: ${AZURE_STORAGE_CONNECTION_STRING}.
  • Your app’s own AWS key: with s3, an app that sets AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY keeps them, and the fork takes that key, so its other AWS calls keep working.
  • Credentials: the fork reads the real ones with the integration’s SAS (read and list) or key (s3:GetObject and s3:ListBucket), and nothing more. They go to blobfork’s container in the preview, never to your app’s services.
  • S3 in one place: the buckets one s3 forks are read at one endpoint, in one region, with one key.
  • New commits and sleep keep what the app wrote. A preview that has to be made again starts over from the real ones.
  • The addresses answer anyone, whoever may open the preview: your app’s server calls them, and every request to them is signed. Your app’s services wait for the fork to be ready before they start.

database

A database outside the preview, made for each preview and dropped with it.

Setting Takes
neon.project Neon project id Required
neon.parent branch id or name The branch each preview’s branch is forked from. Required; your Neon integration says which may be
neon.integration name Which of your org’s Neon integrations, when there are several
neon.database name neondb by default
neon.role name The role the URLs sign in as, neondb_owner by default
neon.pooled true Whether url is the pooled URL
neon.params map of strings Added to the URLs, e.g. sslmode: verify-full
neon.env map The variables the URLs are given as, by kind (url, pooled, unpooled). url: DATABASE_URL by default

previews

Value
on-demand The default: a preview when someone who can push comments /stagd deploy
always Every pull request gets a preview
{ label: preview } While the pull request has this label. Adding it deploys; removing it tears the preview down

previews: always is short for previews: { when: always }.

commands

Setting Takes
handled delete, collapse or keep What happens to a /stagd comment once Stagd has handled it. delete by default

wait

Setting Takes
checks 1 to 20 names Check runs or workflows on the commit, e.g. [build-images]. One failing fails the preview at once
timeout duration, 1m to 2h How long to wait for them from when the deploy starts. 30m by default

registries

Each key is a registry’s host, e.g. ghcr.io or registry.example.com:5000.

Setting Takes
username string Required
password a secret, "${NAME}" Must be one of your org’s secrets: a password in the repository is a leaked password

lifecycle

Setting Takes
sleep_after duration, 45m to 24h How long a preview nobody opens stays awake
expire_after duration, 1h to 48h How long a preview lives without a new commit

testers

Users your app already has, in its seed or let in by a test login: Stagd never makes them. Stagd signs in as them to check that signing in works (stagd preview testers <id> --check, or Check sign-ins on the preview’s Overview), and people see them there, with how to sign in.

testers:
  admin: { email: admin@acme.test, note: org admin, sees billing }
  member: { email: member@acme.test }
  api: { token: "${API_TOKEN}", sign_in: token }
Setting Takes
email, username, password, token string, or a secret as "${NAME}" What the sign-in’s steps and headers use, as ${tester.email} and so on
note string, up to 200 characters Who they are, for people and for tests: e.g. “org admin, sees billing”
sign_in a name under sign_in Which sign-in it uses. Left out when there’s only one

A password written out is shown to members on the preview’s Overview. Use a secret for one that matters.

sign_in

Each sign-in is a form a browser fills in, or headers sent with every request, and says how Stagd tells it worked (signed_in).

sign_in:
  email-code:
    form:
      url: /login
      steps:
        - fill: { field: Email, value: "${tester.email}" }
        - click: Send code
        - wait_for_mail: { subject: Your sign-in code }
        - fill: { field: Code, value: "${mail.code}" }   # or "123456", with a test login
        - click: Sign in
    signed_in: { text: Sign out }
  token:
    headers: { Authorization: "Bearer ${tester.token}" }
    signed_in: { request: /api/me }
Setting Takes
form.url path The sign-in page on the primary ingress, e.g. /login
form.steps list, up to 20 What the browser does, in order (below)
headers map of header names and values Sent with every request: an API’s token
signed_in one of text, url, request text: it shows on the page. url: the browser ends on this path, a * matching the rest. request: a GET of this path answers 2xx, which headers needs
Step
fill: { field, value } Types into a field, found by its label, placeholder or name
click: <text> Clicks a button or link, found by its text
open: <path> Goes to a path on the preview, or "${mail.link}"
wait_for: <text> Waits for the text to show on the page
wait_for_mail: { … } Waits for an email the app sent after the sign-in started, and reads ${mail.code} and ${mail.link} from it. Needs services: { mail: {} }

wait_for_mail takes to (${tester.email} by default), subject (part of it), within (5s to 2m, 30s by default), code (a regular expression whose first group is the code; by default the first 4 to 8 digits on their own) and link (a regular expression for the link; by default the first one to the preview).

Values can use ${tester.*}, your secrets as ${NAME}, and after wait_for_mail, ${mail.code} and ${mail.link}. Stagd fills them in when it signs in and never shows a secret.

Variables

Stagd fills these in for each preview. Use them in env, build and seed URLs, and in the compose file.

Variable
STAGD_PREVIEW_ID The preview’s id
STAGD_REPOSITORY owner/name
STAGD_BRANCH The branch
STAGD_SHA The commit, in full
STAGD_SHORT_SHA Its first 7 characters
STAGD_PR_NUMBER The pull request’s number, for a pull request’s preview
STAGD_URL The primary URL
STAGD_URL_<NAME> Each ingress’s URL, its name upper-cased with _ for -, e.g. STAGD_URL_SITE

For language models and agents: this page as Markdown, or every page through llms.txt.