The recipe: forkstage.yaml
The recipe is deliberately small. It is not a second compose file; it says what Forkstage needs to bake and fork: the services, the app’s port, how data gets in, when the stack counts as ready, and how to test it.
A complete example
Section titled “A complete example”stack: orders-apiservices: app: image: node:22 # run from an image… source: . # …with the repository mounted at /app setup: npm install # once, before the command command: npm run dev port: 3000 env: DATABASE_URL: ${db.url} depends_on: - db db: image: postgres:16 port: 5432 data: seed: npm run db:seed # a command in the app, or a .sql fileready: - http: app/healthmigrate: npm run db:migratetests: - name: unit run: npm testTwo ways to run the app
Section titled “Two ways to run the app”Built from a Dockerfile (build: .): Forkstage builds the image on the host during the bake, exactly as your Dockerfile says. Best when you already ship a Dockerfile. Tests then run inside the final image, so they can only use what that image contains.
Run from an image (image: plus source:): the repository is mounted at /app inside a stock image (node:22, python:3.12…), setup installs dependencies once during the bake, and command starts the app. Best for projects without a Dockerfile, and for fast iteration since nothing is rebuilt.
A service has one or the other, never both.
Placeholders in env
Section titled “Placeholders in env”Forkstage fills these in from the services in the same recipe:
| Placeholder | Becomes |
|---|---|
${db.url} |
postgres://forkstage:forkstage@db:5432/app (or MySQL / Redis equivalents by image) |
${db.host}, ${db.port} |
the service’s name and port |
Data stores get fixed credentials inside a fork: user forkstage, password forkstage, database app. They are only reachable from inside the fork.
data: empty means schema only: your migrations run, no rows. data: { seed: … } loads rows during the bake, from a .sql file (fed to psql in the database service) or a command run in the app. Migrations run before seeds. If your app migrates itself on start, leave migrate out.
A list of checks; the stack counts as up when all pass. http: service/path expects a 2xx or 3xx. tcp: service expects a connection on the service’s port. run: command expects exit 0, in the app unless in: says otherwise. The first http check is also what the bake waits for.
Each entry is a command run inside a service (the app by default, or in: db). forkstage test runs them all and records counts it can read from the output (Jest, Vitest, node:test, pytest, Go test, JUnit summaries). The GitHub App runs the same list on every pull request.
Resources
Section titled “Resources”resources: cpu: 4 memory: 4GiThe microVM’s size. Defaults are 4 vCPUs and 3 GiB; a Maven build inside the bake is comfortable at that.
Reserved for later
Section titled “Reserved for later”outside (how the stack reaches third-party hosts: record and replay, sandbox keys, block) and data: production-shaped are in the schema but not active in the hosted service yet. Leaving them out is correct today.
Every field, with types and defaults: Recipe fields.