Field index

Every field the spec accepts, one row each. The decoder is strict: an unknown key fails the parse with its line number rather than being ignored.

Top level

Field	Type	Required	Notes
`version`	int	Required.	Must be `1`.
`services`	list	Required.	At least one. A list of blocks, each starting `- name:`, never a map keyed by name.
`databases`	list	Optional.	Each entry becomes a service. See Databases.
`autoDeploy`	bool	Optional.	Whether a push to the tracked branch redeploys. Omit to leave the console toggle in charge.
`buildFilter`	object	Optional.	See below.
`previews`	object	Optional.	See below.

buildFilter

Field	Type	Notes
`paths`	list of globs	A changed file must match one of these. Empty means all files match.
`ignoredPaths`	list of globs	A changed file matching any of these does not count.

At least one of the two must be non-empty. Patterns are doublestar globs, so ** crosses directories, and are relative to the repository root even when a service sets rootDir.

previews

Field	Type	Notes
`generation`	string	`automatic`, `manual` or `off`.

databases[]

Field	Type	Required	Notes
`name`	string	Required.	`^[a-z][a-z0-9-]{0,30}$`, unique, and must not collide with a `services:` name.
`engine`	string	Required.	`postgres`, `redis`, `mysql` or `clickhouse`.
`version`	string	Optional.	Defaults to the newest offered. `latest` is rejected.
`diskSizeGB`	int	Required except on `redis`.	1 to 1024.
`cpu`	cores or millicores	Optional.	Defaults to `500m`.
`memory`	memory	Optional.	Defaults to the larger of 512Mi and the engine’s floor.

services[]

Identity

Field	Type	Required	Notes
`name`	string	Required.	`^[a-z][a-z0-9-]{0,30}$`, unique within the project.
`type`	string	Optional.	`web` (default), `worker`, `cron` or `static`.
`enabled`	bool	Optional.	Defaults to true. False keeps the config and tears the workload down on the next deploy.

Source

A service declares image: or the build fields, never both.

Field	Type	Applies to	Notes
`image`	string	web, worker, cron	A pullable reference. Rejected on `static`.
`rootDir`	string	all built services	Defaults to `.`.
`dockerfilePath`	string	web, worker, cron	Mutually exclusive with `runtime`.
`dockerContext`	string	web, worker, cron	Narrows the build context below `rootDir`.
`dockerTarget`	string	web, worker, cron	A build stage. Mutually exclusive with `runtime`.
`buildArgs`	map	all built services	Values may carry `${secret.}`, `${var.}` and `${service.*}`.
`runtime`	string	all built services	`docker`, or `node`, `python`, `go`, `ruby`, `rust`, `elixir`.
`runtimeVersion`	string	language runtimes	Requires `runtime`. See Language runtimes.
`buildCommand`	string	language runtimes, static	The build step, not the start command.

Networking

Field	Type	Applies to	Notes
`ports`	list	web only	Rejected on worker, cron and static.
`ports[].port`	int		1 to 65535.
`ports[].public`	bool		At most one port per service may be public.
`prefix`	string	static, or web with a public port	`^[a-z][a-z0-9-]{0,30}$`. Defaults to the service name.
`domain`	string	static, or web with a public port	Must be a zone your organization has verified.
`auth`	object	web with a public port	See below. Rejected on worker, cron and static.
`ipRules`	list	web with a public port, static, external databases	Inbound IPv4 allowlist. Rejected on worker and cron.
`edgeCache`	string	web with a public port	`off` (default), `static` or `all`. Rejected on worker, cron, static and databases.

prefix and domain sit on the service, never inside a port entry. auth:

Field	Type	Notes
`token`	bool	Ask for the project’s shared token.
`members`	bool	Ask the visitor to sign in with GitHub or GitLab.

Both default to false, which leaves the service open. See Access controls. ipRules entries:

Field	Type	Notes
`cidr`	string	IPv4 address or CIDR range, like `203.0.113.0/24`. IPv6 is rejected.
`description`	string	Optional note shown in the console.

No ipRules: block allows every IP; an empty list blocks everything. At most 50 entries per service. See Inbound IP rules. edgeCache turns on response caching at the platform edge for the service’s public URL: static caches asset-shaped paths only, all caches every cacheable response. See Edge caching.

Configuration

Field	Type	Applies to	Notes
`env`	map	all	Values may carry substitutions.
`command`	list	web, worker, cron	Overrides the image entrypoint. Rejected on static.
`args`	list	web, worker, cron	Rejected on static.
`workDir`	string	web, worker, cron	Absolute. Rejected on static.
`files`	list	web, worker, cron	`"<repo-path>:<container-path>"`. Source relative to the spec with no `..`, target absolute. About 1 MB each.
`dependsOn`	list	web, worker	Must name an existing, enabled, non-cron, non-static service. The graph must be acyclic.
`preDeploy`	list	web, worker, cron	A one-shot job in the freshly built image. The deploy proceeds only on exit 0.
`maxShutdownDelaySeconds`	int	web, worker	1 to 300. 0 uses the platform default of 30.
`schedule`	string	cron only, required	Five-field UTC cron. No seconds field and no descriptors.
`timeout`	duration	cron only	One run’s limit, `10s`–`24h`. Default `1h`.
`concurrencyPolicy`	string	cron only	`skip` (default), `allow` or `replace`.
`maxConcurrentRuns`	integer	cron, with `allow`	`1`–`10`. Default `10`.

Health

Field	Type	Applies to	Notes
`healthCheckPath`	string	web only	Must start with `/`. Mutually exclusive with `healthcheck`.
`healthcheck`	object	web, worker	`startup`, `readiness` and `liveness`, each a probe. Rejected on cron and static.

A probe declares exactly one of:

Kind	Fields
`http`	`path` (required, absolute), `port`
`tcp`	`port`
`exec`	`command`, a list
`grpc`	`port`, `service`

Plus optional periodSeconds, timeoutSeconds, failureThreshold, successThreshold and initialDelaySeconds, all non-negative.

Compute

Field	Type	Applies to	Notes
`cpu`	cores or millicores	not static	Minimum `100m`, multiples of `50m`. Defaults to `500m`.
`memory`	memory	not static	Minimum `128Mi`, multiples of `128Mi`. Defaults to `512Mi`.
`replicas`	int	web, worker	0 to 20. Mutually exclusive with `scaling`, and forbidden above 1 with a disk.
`scaling`	object	web, worker	See below. Rejected on cron and static.
`highAvailability`	boolean	managed Postgres, managed Redis	Runs a primary plus replicas with automatic failover instead of a single copy. `replicas` and `scaling` do not apply to a managed database in either mode; a disk is required.
`haMembers`	int	managed Postgres, managed Redis	How many copies `highAvailability` runs. Minimum 3, maximum 20, default 3. Needs `highAvailability: true`.
`connectionPooling`	boolean	managed Postgres	Runs a PgBouncer pooler (transaction mode) in front of the database at `<name>-pool:5432`. Postgres only; siblings can wire `${service.<name>.pooled_url}`.
`command`	list	—	Not permitted on a managed database. The platform owns the server invocation; tune it with the engine’s environment variables instead.
`autoResize`	object	web, worker	See below. Rejected on cron and static.

scaling:

Field	Range	Notes
`min`	1 or more
`max`	`min` to 20	Forbidden above 1 with a disk.
`targetCPUPercent`	0 to 100	Defaults to 70 when neither target is set.
`targetMemoryPercent`	0 to 100

autoResize:

Field	Range	Default
`enabled`	bool	Absent means on. Write `false` to disable.
`maxCPU`	at or above the service’s `cpu`	The plan cap
`maxMemory`	at or above the service’s `memory`	The plan cap
`cpuThresholdPercent`	50 to 99	90
`memoryThresholdPercent`	50 to 99	85
`sustainedSeconds`	60 to 3600	180
`stepPercent`	105 to 400	150
`cooldownSeconds`	60 to 86400	600

Storage

Field	Type	Applies to	Notes
`disk.mountPath`	string	web, worker	Absolute, and not `/`.
`disk.sizeGB`	int	web, worker	1 to 1024.

One disk per service, and no two services share one. Rejected on cron and static.

Previews

Field	Type	Applies to
`previews.env`	map	web, worker
`previews.cpu`	cores or millicores	web, worker
`previews.memory`	memory	web, worker

Rejected on cron and static. Per-service preview env set in the console (the service’s Previews tab) merges over previews.env, console winning per key.

Static sites

Field	Type	Required	Notes
`publish`	string	Required.	Relative to `rootDir`, not absolute, no `..`.
`notFound`	string	Optional.	An absolute path such as `/index.html`.
`redirects`	list	Optional.	See below.
`headers`	list	Optional.	See below.

redirects[]:

Field	Required	Notes
`from`	Required.	Absolute. A splat `*` may appear only at the end.
`to`	Required.	An absolute path, or a full URL for a redirect.
`status`	Optional.	One of 200, 301, 302, 303, 307, 308, 404. Defaults to 301. `200` to an external URL is rejected.
`force`	Optional.	Makes the rule beat a real file.

headers[]:

Field	Required	Notes
`for`	Required.	Absolute. A splat only at the end.
`values`	Required.	At least one. `Content-Length`, `Content-Encoding`, `Transfer-Encoding`, `Connection` and `Host` are refused.

Substitution

Valid in env and buildArgs only.

Syntax	Resolves to
`${secret.NAME}`	A secret, this service’s value first, then the project’s
`${secret.env.NAME}`	Project scope only, strict
`${var.NAME}`, `${var.env.NAME}`	The same two shapes for variables
`${service.NAME.FIELD}`	A sibling service, see below
`${NAME}`	Deprecated alias for `${secret.NAME}`. Emits a warning.

${service.NAME.FIELD} accepts url, host, port, public_url, external_url, pooled_url, user, password, database, bucket, endpoint, access_key_id and secret_access_key. See Secrets and variables and Service to service.

Platform environment variables

Set on every workload without being declared.

Variable	Value
`IS_PULL_REQUEST`	`true` in a preview, `false` otherwise. Always set.
`SLIPWAY_PREVIEW`	`true` in a preview
`SLIPWAY_PR_NUMBER`	The pull request number, in a preview

Rejected fields

These fail the parse with a message naming the replacement.

Where	Field	Replacement
top level	`volumes`	`disk:` on each service
top level	`predeploy`	`preDeploy:` on the service
service	`build`	The build fields, flattened onto the service
service	`volumes`	`disk:`
service	`workdir`	`workDir`
service	`depends_on`	`dependsOn`
service	`size`	`cpu:` and `memory:`
port entry	`prefix`	`prefix` on the service
port entry	`domain`	`domain` on the service

A services: map keyed by service name is also rejected, with a message pointing at the list form.

Get started

Quickstarts

Services

Data

Deploys

Previews

slipway.yaml

Networking

Projects

Observability

Integrations

Organization

Clusters

Reference

Top level

buildFilter

previews

databases[]

services[]

Identity

Source

Networking

Configuration

Health

Compute

Storage

Previews

Static sites

Substitution

Platform environment variables

Rejected fields

​Top level

​buildFilter

​previews

​databases[]

​services[]

​Identity

​Source

​Networking

​Configuration

​Health

​Compute

​Storage

​Previews

​Static sites

​Substitution

​Platform environment variables

​Rejected fields

Top level

buildFilter

previews

databases[]

services[]

Identity

Source

Networking

Configuration

Health

Compute

Storage

Previews

Static sites

Substitution

Platform environment variables

Rejected fields