Your own project
What a project needs
Section titled “What a project needs”One of:
- a
docker-compose.yml(orcompose.yaml) that starts your services, or - a
Dockerfilefor the app, or - a
package.json,pyproject.toml,pom.xmlorgo.modfrom which Forkstage can guess a runtime image.
The more the repository already says, the less you edit. A compose file is the best source: it names the services, their ports and their environment.
1. Run init
Section titled “1. Run init”In the repository’s folder (or, in a monorepo, in the folder of the service you want to fork):
forkstage initIt writes forkstage.yaml and prints what it found and what it could not decide:
Services app build . :8080 db postgres:16 :5432 data: empty Ready when GET app/health Tests sh tests/smoke.sh
Next: forkstage bake, then forkstage up.Use forkstage init --print to see the result without writing it, and --force to overwrite an existing file.
2. Read the file and fix what init could not know
Section titled “2. Read the file and fix what init could not know”Open forkstage.yaml. The three lines that matter most:
ready: how Forkstage knows the stack is up. It scans your code for a health route (/health, /healthz, /actuator/health, /ping, /status, /ready). If none is found it assumes / and says so; set it to a URL that answers 2xx when the app is ready, or a bake will wait for a page that never answers.
ready: - http: app/healthtests: commands run inside the app container by forkstage test and by the GitHub App. They must exist in the runtime image: if your Dockerfile’s final stage has no Maven or no dev dependencies, point at a script that uses what is there (a curl-based smoke test is a good start).
tests: - name: unit run: npm testdata and migrate: how the database is filled before the snapshot. If migrations run when your app starts (Flyway, Prisma migrate deploy in the entrypoint, Django on boot), you need nothing. Otherwise name the command and, for seed rows, a SQL file or a command:
migrate: npm run db:migrateservices: db: image: postgres:16 port: 5432 data: seed: db/seed.sqlThe full field list is in Recipe fields.
3. Bake, fork, check
Section titled “3. Bake, fork, check”forkstage bakeforkstage upOpen the address. If the bake never becomes ready, Troubleshooting has the three usual causes.
Commit the file
Section titled “Commit the file”forkstage.yaml belongs in the repository, next to the compose file. It is the team’s description of how the stack stands up for a task, and the GitHub App reads it from there.
Monorepos
Section titled “Monorepos”Run forkstage init and forkstage bake in the folder of the service. The stack remembers its folder; when a pull request touches files outside it, the GitHub App ignores those parts of the diff.
Several stacks in one workspace
Section titled “Several stacks in one workspace”Each repository (or folder) is its own stack, named after its folder by default (stack: in the file). A workspace can hold as many as you like; limits apply per workspace, not per stack.