> ## Documentation Index
> Fetch the complete documentation index at: https://docs.slipway.sh/llms.txt
> Use this file to discover all available pages before exploring further.

# Field index

> Look up every slipway.yaml field, its type and its constraints.

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](/slipway-yaml/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](/services/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](/networking/access-control).

`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](/networking/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](/networking/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](/slipway-yaml/secrets-and-variables) and
[Service to service](/networking/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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.