Skip to content

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.

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
PatchulaConfig.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
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