# 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](https://stagd.dev/docs/guides/describe-your-app.md) walks through it; this page lists every setting.

```yaml
# 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](#variables) and your org's secrets: `${NAME}`.

## Top level

| Setting | Takes | |
|---|---|---|
| `version` | `1` | The file's format. Required |
| `app` | [app](#app) | Where the app is described |
| `ingress` | map of [ingresses](#ingress) | The preview's URLs. When set, the compose file's `dev.stagd.*` labels are ignored |
| `build` | map of [builds](#build) | Where each service's image comes from, by the compose file's service name |
| `services` | [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](#database) | A database outside the preview: a Neon branch per preview |
| `previews` | [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](#commands) | What happens to `/stagd` comments |
| `wait` | [wait](#wait) | GitHub checks that must pass before a commit deploys |
| `registries` | map of [registries](#registries) | Logins for pulling private images, by the registry's host |
| `lifecycle` | [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](#testers) | Users Stagd signs in as on the preview, by name |
| `sign_in` | map of [sign-ins](#sign_in) | 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](#mail-and-sms) |
| `sms` | Catches the text messages your app sends through Amazon SNS, for the preview's Messages tab. See [mail and sms](#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](#otel), and [Traces in previews](https://stagd.dev/docs/guides/traces.md) to make your app send |
| `postgres` | A Postgres database. See [databases](#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](#azure_blob-and-s3) |
| `s3` `beta` | A fork of your S3 buckets, as `azure_blob` is. See [azure_blob and s3](#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`](#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](https://stagd.dev/docs/guides/traces.md) 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](#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

```yaml
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](https://wiki.postgresql.org/wiki/Apt) | `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

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

Each runs [blobfork](https://github.com/stagdhq/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.

```yaml
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](#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`).

```yaml
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` |
