.stagely.yml file reference

One small file in your repository tells Stagely how to run a pull request as a stagelet: the Compose files, the public service and port, and the health path.

Put .stagely.yml in the root of your repository. For each deploy, Stagely reads these files at the pull request’s head commit, through the GitHub API: .stagely.yml, the Compose files that it names, and the files that those Compose files reference. Stagely does not clone your repository.

version: 1
compose:
  - deploy/compose.yml
public:
  service: web
  port: 8080
health:
  path: /healthz
migration:
  command: bin/rails db:migrate

Fields

Field	Required	Meaning
`version`	yes	Always `1`
`compose`	yes	Compose files, as paths relative to the repository root. Stagely combines them like `docker compose -f a.yml -f b.yml`.
`public.service`	yes	The Compose service that people open
`public.port`	yes	The port that service listens on, 1 to 65535
`health.path`	yes	A path on the public service that answers with a 2xx status when the app is ready. It must start with `/`.
`migration.command`	no	One line that runs with `sh -c` in the public service, after the services start and before the health check. A failed migration fails the deploy. A reset does not run it.

An unknown field is an error. Stagely refuses a deploy when .stagely.yml is invalid. When a GitHub event asked for the deploy, such as a push, a label or a comment command, the pull request shows the reason: as a reply to the comment command, or as an error commit status. When the console or MCP asked for the deploy, Stagely returns the reason to the person or agent that asked. Nothing goes on the pull request.

How a stagelet runs your project

A build worker in your cloud builds every service that has a build section, and pushes its image to your registry.
The stagelet’s own machine runs the resolved project, with each built service pinned to its image digest.
The stagelet’s machine never receives the source. A service can’t read files from the repository at run time, so build the files that it needs into its image.

Relative paths resolve the way docker compose -f resolves them: against the directory of the first Compose file in compose.

The health check

Two checks use health.path.

During a deploy, the agent checks health first, from inside the stagelet’s machine. It sends a request to http://127.0.0.1:<port><path>, with the port from public.port and the path from health.path. This request carries no stagelet host name. The agent retries until the app answers with a 2xx status, for up to two minutes.

After the deploy, the gateway checks health every 20 seconds. It sends GET <health path> to the public service, with the stagelet’s host name in the Host header and a 5-second timeout. The app is healthy when it answers with a 2xx status. The gateway does not follow redirects, so point health.path at a path that answers directly.

If your app checks the Host header, for example with Django’s ALLOWED_HOSTS, it must accept 127.0.0.1 on the health path.

Config in your Compose files

Every service gets each plain config value and each secret as an environment variable. These values replace the values of the same variables in your Compose files. Compose files can use plain config values as variables, such as image: postgres:${POSTGRES_VERSION}. Compose files can’t use secrets as variables. See Config values and secrets.

include, extends and env_file

Stagely follows these references, and checks every Compose file it reaches against the Compose rules.

Reference	Resolved against
`include` (short or long form, with `project_directory` and `env_file`)	The project directory of the file that names it. An included file’s own references resolve against its own directory, or its `project_directory`.
`extends.file`	The directory of the file that names it. Without `file`, the service must be in the same file.
`env_file` (a string, a list, or entries with `path` and `required`)	The project directory of the file that names it. An entry with `required: false` can be missing.

A plan fails, with an error that names the reference, when:

a referenced file does not exist at the commit,
a path points outside the repository,
a path is a URL, such as a remote include, or
a path uses a variable, such as ${STAGE}.env.

A plan reads at most 32 files, and references nest at most 4 levels deep.

Stagely stores the resolved Compose model and the contents of env_file files in the deploy bundle that it keeps for resets. Put secret values in secrets, not in env_file files.