Docs / Reference / 03
watchdep.yml
Generated from the CLI's JSON schema and its annotated example.
What no lockfile states about a part. Every key is optional. Version 1.
The file sits at the root of a part (the folder watchdep scan or watchdep gate runs in). Every key is optional, so most projects need no file at all.
An annotated example
# watchdep.yml: what no lockfile states about this part.
# Place it at the root of the part. Every key is optional.
# The schema is schema/watchdep.schema.json; the CLI and the server read it with the same code.
version: 1
# The branch whose head (or last deployment) is production. Pinning it here overrides the
# server's setting for this part.
production_branch: main
# The runtime versions production actually runs. Quote versions so YAML keeps them as written.
# When a version file (.ruby-version, .nvmrc, .python-version, .tool-versions) says something
# else, both are listed and the output says they disagree.
runtimes:
ruby: "3.3.4"
node: "20.11.1"
# Database engines and versions in production.
databases:
- engine: postgres
version: "16"
- engine: redis
version: "7.2"
# Runtimes the hosting platform provides.
hosting:
- name: heroku-stack
version: "24"
# Base images built or pulled elsewhere that production runs on. The CLI reads them with
# watchdep inventory --image; the server pulls public ones.
images:
- ruby:3.3.4-slim-bookworm
# Folders, relative to this file, that are not part of this part.
ignore:
- docs/
- spec/fixtures/
Every key
A * marks a key that must be present when its parent is.
| Key | Type | What it is |
|---|---|---|
| version | always 1 | The file's format version. 1 when absent. |
| production_branch | string | The branch whose head, or last deployment, is production. at least 1 character |
| runtimes | map | Runtime name to the version production runs, for example ruby: "3.3.4". keys match ^[a-z][a-z0-9_.-]*$ |
| databases | list of objects | |
| engine * | string | postgres, mysql, redis, sqlite and so on. at least 1 character |
| version * | string or number | A version. Quote it to keep trailing zeros: "3.10". |
| hosting | list of objects | Runtimes the hosting platform provides, for example a Heroku stack. |
| name * | string | at least 1 character |
| version * | string or number | A version. Quote it to keep trailing zeros: "3.10". |
| images | list of string | Base images built or pulled elsewhere that production runs on. |
| ignore | list of string | Folders, relative to this file, that are not part of this part. |
How it is read
- An unknown key or a value of the wrong type stops the run with exit code 3, naming the line. A mistyped key is never silently ignored.
- Runtimes also come from
.ruby-version,.nvmrc,.node-version,.python-versionand.tool-versions. When a version file andwatchdep.ymlin the same folder disagree, both are listed and the output says they disagree. - The CLI and the server read the file with the same schema, so a file the CLI accepts is a file the server accepts.