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 EXTENSIONmakes 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 setsAWS_ACCESS_KEY_IDandAWS_SECRET_ACCESS_KEYkeeps 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:GetObjectands3: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
s3forks 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 |