Configuration schema
This is the complete repository schema, PatchulaConfig.pkl, bundled with every
build. Print it with patchula config schema. The configuration guide
explains how the pieces fit together.
Top-level fields
Section titled “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 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
Section titled “The schema”/// 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© 2026 Sweepy
