# Configuration schema

> The complete PatchulaConfig.pkl repository schema, with every field, type and default.

This is the complete repository schema, `PatchulaConfig.pkl`, bundled with every build. Print it with `patchula config schema`. The [configuration guide](https://count-patchula.sweepy.dev/guide/configuration/) explains how the pieces fit together.

## Top-level fields

| Field | Type | Default |
| - | - | - |
| `managers` | `Listing<Manager>` | every manager |
| `defaults` | `Policy` | see the schema |
| `rules` | `Listing<Rule>` | two built-in rules: [reference data](https://count-patchula.sweepy.dev/guide/configuration/#reference-data) fast-tracked, and `preserve` for Cargo, pyproject, Bundler and Composer |
| `files` | `Listing<FileSet>` | each manager’s own patterns |
| `extractors` | `Listing<Extractor>` | none |
| `ignore` | `Listing<String>` | none |
| `exclude` | `Listing<String>` | `**/node_modules/**`, `**/bower_components/**`, `**/vendor/**`, `**/.git/**`, `**/test/**`, `**/tests/**`, `**/__tests__/**`, `**/__fixtures__/**`, `**/fixtures/**`, `**/examples/**` |
| `prs` | `PullRequests` | see the schema |
| `lockfiles` | `Lockfiles` | see the schema |
| `security` | `Security` | see the schema |
| `warnings` | `Warnings` | see the schema |
| `gitlab` | `Gitlab` | see the schema |
| `useVersionsHost` | `Boolean` | `true` |

## The schema

`PatchulaConfig.pkl`

```pkl
/// Count Patchula's configuration schema, with its explicit defaults. Vendor it
/// with `patchula config schema > PatchulaConfig.pkl` and amend this module, or
/// amend an organisation module that itself amends this one.
module PatchulaConfig

typealias Manager =
  "npm"
    | "bun"
    | "github-actions"
    | "mise"
    | "cargo"
    | "dockerfile"
    | "compose"
    | "go"
    | "terraform"
    | "kubernetes"
    | "kustomize"
    | "flux"
    | "helm-values"
    | "pyproject"
    | "pre-commit"
    | "helm"
    | "devcontainer"
    | "woodpecker"
    | "copier"
    | "maven"
    | "gradle"
    | "nuget"
    | "bundler"
    | "composer"
    | "gitlabci"
    | "gitlabci-include"
    | "nix"
    | "apm"
    | "regex"
typealias Source =
  "npm"
    | "github-releases"
    | "github-tags"
    | "github-runners"
    | "docker"
    | "crates"
    | "go"
    | "terraform"
    | "pypi"
    | "helm"
    | "oci"
    | "mise"
    | "forge-tags"
    | "maven"
    | "nuget"
    | "rubygems"
    | "packagist"
    | "nix"
typealias Update = "major" | "minor" | "patch" | "digest" | "pin"
typealias VersionPolicy = "exact" | "preserve" | "widen"
typealias ToolingWarning =
  "merge-without-ci" | "merge-without-required-checks" | "security-merge-without-delivery"
typealias ReleaseChannel = "stable" | "lts"
typealias Scheme =
  "semver"
    | "docker"
    | "pep440"
    | "poetry"
    | "maven"
    | "nuget"
    | "rubygems"
    | "composer"
    | "go"
    | "hashicorp"
    | "loose"
/// Dependency roles emitted by first-release managers. npm/bun use the first
/// four roles; Cargo also uses build. Ordinary Go/Python/regex packages use
/// production. Actions distinguish steps from reusable workflows; containers,
/// mise tools, Go language directives, Terraform providers/modules and Helm
/// charts have explicit roles. A `transitive` package is one only a lockfile
/// records; it gets an update only to fix an advisory. These are exact values,
/// not match patterns.
typealias DependencyKind =
  "production"
    | "development"
    | "peer"
    | "optional"
    | "build"
    | "action"
    | "reusable-workflow"
    | "runner"
    | "container-image"
    | "tool"
    | "go-directive"
    | "toolchain"
    | "provider"
    | "module"
    | "chart"
    | "template"
    | "reference-data"
    | "transitive"
    | "flake-input"

/// Match lists are OR; populated selector fields are AND. Empty means any.
/// Patterns are path-aware globs, or `regex:...`; prefix `!` excludes a match.
/// Version filters are `semver:...`, `regex:...`, or their `!` negations.
/// `semver:` ranges use the dependency's own versioning; a scheme without
/// ranges, such as a loose tag, rejects the filter.
class Selector {
  packages: Listing<String> = new {}
  dependencies: Listing<String> = new {}
  managers: Listing<Manager> = new {}
  files: Listing<String> = new {}
  updates: Listing<Update> = new {}
  sources: Listing<Source> = new {}
  kinds: Listing<DependencyKind> = new {}
  current: String? = null
}

class Window {
  /// Five-field cron expressions in the named IANA timezone; weekday 0 or 7 is
  /// Sunday. Each time they name is due on the first run after it.
  cron: Listing<String> = new {}
  zone: String = "UTC"
}

/// Policy applied before rules. No implicit grouping, and nothing merges by
/// default except reference data, through the built-in rule below.
class Policy {
  active: Boolean = true
  /// `exact` pins every declaration. The built-in rules below set `preserve`
  /// for Cargo, pyproject, Bundler and Composer.
  versions: VersionPolicy = "exact"
  /// `lts` keeps releases on the catalog's `lts` dist-tag line; `stable`,
  /// the default, selects the newest release the other rules allow.
  channel: ReleaseChannel = "stable"
  /// Actions, reusable workflows and APM packages.
  actionDigests: Boolean = true
  /// Container images and OCI Helm charts.
  imageDigests: Boolean = true
  merge: Boolean = false
  /// Nonempty groups share a PR; an empty string forces individual PRs.
  group: String? = null
  labels: Listing<String> = new { "dependencies" }
  commitPrefix: String = "chore(deps):"
  releaseNotes: Boolean = true
  bodyNotes: Listing<String> = new {}
  permitted: String? = null
  /// Minimum release age when the source reports a date. Current pins are retained.
  waitHours: Int = 24
  /// An empty window list means updates may be proposed at any time.
  windows: Listing<Window> = new {}
}

/// Null leaves an earlier policy unchanged. Rules apply in declaration order;
/// scalars and lists replace earlier values. `digest` overrides source defaults.
class Overrides {
  active: Boolean? = null
  versions: VersionPolicy? = null
  channel: ReleaseChannel? = null
  digest: Boolean? = null
  merge: Boolean? = null
  group: String? = null
  labels: Listing<String>? = null
  commitPrefix: String? = null
  releaseNotes: Boolean? = null
  bodyNotes: Listing<String>? = null
  permitted: String? = null
  waitHours: Int? = null
  windows: Listing<Window>? = null
}

class Rule {
  note: String = ""
  select: Selector = new {}
  apply: Overrides = new {}
}

class FileSet {
  manager: Manager
  /// Replaces that manager's built-in file selection; empty is invalid.
  paths: Listing<String>
}

/// Regex captures use Rust regex syntax: (?<current>...), (?<dependency>...).
/// Templates substitute {capture} only; no expressions or executable helpers.
class Extractor {
  note: String = ""
  paths: Listing<String>
  patterns: Listing<String>
  source: String = "{source}"
  dependency: String = "{dependency}"
  package: String = "{dependency}"
  /// A Scheme name or a template such as "{scheme}".
  scheme: String = "semver"
  /// Optional tag regex with a required named `version` capture.
  extract: String? = null
  /// The https URL of the registry to look the package up in, or a template
  /// such as "{registry}", when it is not the source's public one. Only npm
  /// and pypi take a registry.
  registry: String? = null
}

class PullRequests {
  /// Open PRs at once. Updates past the limit wait for a PR to close; the
  /// dashboard lists them. Security fixes never wait. Null means unlimited;
  /// positive integers set a limit. Zero is invalid.
  concurrent: Int? = 10
  /// New PRs per hour. Null, the default, means unlimited; security fixes
  /// never wait.
  perHour: Int? = null
  /// Keep one Dependency Dashboard issue per repository. `false` turns it off
  /// and closes the issue.
  dashboard: Boolean = true
  /// Every branch name starts with this. At most 200 characters.
  branch: String = "patchula/"
  rebase: "conflicts" | "behind" = "conflicts"
  /// The batch PR collects updates whose "Add to batch" box was ticked. It
  /// only auto-merges when this is true, behind the usual check gates.
  batchMerge: Boolean = false
}

class Lockfiles {
  refresh: Boolean = false
  waitHours: Int = 0
  group: String = "lockfile refresh"
  tidyGo: Boolean = false
  /// Engine that regenerates npm lockfiles: aube by default, or native npm.
  /// pnpm and Yarn lockfiles always use aube and Yarn respectively.
  npmEngine: "aube" | "npm" = "aube"
  /// PHP for composer.lock: a prebuilt static binary, or PHP compiled from
  /// source by mise, which needs a C toolchain and development libraries.
  php: "static" | "compiled" = "static"
}

/// GitLab CI files.
class Gitlab {
  /// The GitLab instance whose projects `include: project:` names, and that
  /// `$CI_SERVER_FQDN` means in a component reference. Its tags are read
  /// unauthenticated, so the host must be gitlab.com or have a `gitlab` label
  /// in its name, such as gitlab.example.com.
  host: String = "gitlab.com"
}

/// Known vulnerabilities, from OSV.dev.
class Security {
  /// Check each dependency's current version against OSV.dev, and mark updates
  /// that leave an advisory behind. Only package names and versions are sent.
  advisories: Boolean = true
  /// Added to PRs with an update that fixes an advisory. Empty adds none.
  label: String = "security"
  /// Applied after `rules` to updates that fix an advisory. By default they
  /// skip the release-age wait and schedule windows, get a PR of their own and
  /// a `fix(deps):` commit prefix, so release tooling that releases on `fix`
  /// ships them. Their PRs never wait for `prs.concurrent` or `prs.perHour`
  /// either.
  apply: Overrides = new {
    waitHours = 0
    windows = new Listing {}
    group = ""
    commitPrefix = "fix(deps):"
  }
  /// When no proposal fixes as many advisories as some release could, also
  /// propose the lowest release that fixes the most, even if `permitted` or
  /// `channel` would hold it back. `active` and the release-age wait from
  /// `apply` still count.
  lowestFix: Boolean = true
  /// Compare the OS packages in a pinned image's old and new SBOMs through
  /// OSV.dev, and mark a digest change that leaves an advisory behind as a
  /// security update. Needs `advisories`.
  images: Boolean = true
  /// Image platforms compared, where both digests have them. An image with
  /// none of them is compared on the first platform its index lists.
  imagePlatforms: Listing<String> = new { "linux/amd64" }
  /// Images whose "can't tell" warning is left off PRs, each with the reason.
  /// Keys use the dependency pattern syntax. The dashboard lists them under
  /// "Silenced".
  quietImages: Mapping<String, String> = new {}
}

/// Warnings about tooling that merges on its own without CI, required checks
/// or delivery to back it up.
class Warnings {
  /// Tooling warnings to leave off PRs, each with the reason. The dashboard
  /// lists silenced warnings and their reasons in a collapsed line.
  quiet: Mapping<ToolingWarning, String> = new {}
}

/// All first-release managers are selected unless a repository replaces this list.
managers: Listing<Manager> = new {
  "npm"
  "bun"
  "github-actions"
  "mise"
  "cargo"
  "dockerfile"
  "compose"
  "go"
  "terraform"
  "kubernetes"
  "kustomize"
  "flux"
  "helm-values"
  "pyproject"
  "pre-commit"
  "helm"
  "devcontainer"
  "woodpecker"
  "copier"
  "maven"
  "gradle"
  "nuget"
  "bundler"
  "composer"
  "gitlabci"
  "gitlabci-include"
  "nix"
  "apm"
  "regex"
}
defaults: Policy = new {}
/// Rules apply in order after `defaults`. The first two are built in; assigning
/// a new Listing to `rules` drops both.
///
/// 1. Reference data (CA root bundles, time zone data, the public suffix list)
///    is only useful while current, so its updates skip the release-age wait
///    and schedule windows, get their own PR and merge once checks pass.
/// 2. Cargo, pyproject, Bundler and Composer keep one version per package and a
///    lockfile, so their ranges are preserved and a release a range already
///    allows moves the lockfile alone. The two rules set different fields, so
///    their order does not matter; both come before yours.
///
/// Later rules can change either.
rules: Listing<Rule> = new {
  new Rule {
    note = "Reference data: no wait, no window, its own PR, merged once checks pass."
    select { kinds = new Listing { "reference-data" } }
    apply {
      waitHours = 0
      windows = new Listing {}
      group = ""
      merge = true
    }
  }
  new Rule {
    note =
      "One version per package plus a lockfile: keep ranges, so a pin cannot clash with another requirement on the same package, and move the lock for releases inside them."
    select { managers = new Listing { "cargo"; "pyproject"; "bundler"; "composer" } }
    apply { versions = "preserve" }
  }
}
files: Listing<FileSet> = new {}
extractors: Listing<Extractor> = new {}
/// Dependency identifiers to leave untouched, using the same pattern syntax.
ignore: Listing<String> = new {}
/// Installed, vendored and test-data directories are excluded. Amending adds
/// to the list and a `!` entry re-includes a path; assigning a new Listing
/// replaces it.
exclude: Listing<String> = new {
  "**/node_modules/**"
  "**/bower_components/**"
  "**/vendor/**"
  "**/.git/**"
  "**/test/**"
  "**/tests/**"
  "**/__tests__/**"
  "**/__fixtures__/**"
  "**/fixtures/**"
  "**/examples/**"
}
prs: PullRequests = new {}
lockfiles: Lockfiles = new {}
security: Security = new {}
warnings: Warnings = new {}
gitlab: Gitlab = new {}
/// Prefer mise-versions for public catalogs; false uses the upstream sources.
useVersionsHost: Boolean = true
```
