watchdep
Sign inSource
Docs / Reference / 03

watchdep.yml

Section
Reference
Page
03 of 16
Source
Generated
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.

KeyTypeWhat it is
versionalways 1The file's format version. 1 when absent.
production_branchstringThe branch whose head, or last deployment, is production.
at least 1 character
runtimesmapRuntime name to the version production runs, for example ruby: "3.3.4".
keys match ^[a-z][a-z0-9_.-]*$
databaseslist of objects
engine *stringpostgres, mysql, redis, sqlite and so on.
at least 1 character
version *string or numberA version. Quote it to keep trailing zeros: "3.10".
hostinglist of objectsRuntimes the hosting platform provides, for example a Heroku stack.
name *string
at least 1 character
version *string or numberA version. Quote it to keep trailing zeros: "3.10".
imageslist of stringBase images built or pulled elsewhere that production runs on.
ignorelist of stringFolders, 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-version and .tool-versions. When a version file and watchdep.yml in 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.