Settings
Operator settings, in a Pkl file that amends the bundled PatchulaSettings.pkl.
The CLI (run, lookup, apply, tui) and patchula serve
read the same file. Only the server uses the server section, but the CLI
still checks the whole file, so an invalid server value stops CLI commands
too. Print the schema with patchula config settings-schema and check a file
with patchula config check-settings <path>. Secrets are never settings.
The CLI takes --settings, then PATCHULA_SETTINGS, then
patchula/settings.pkl in the user config directory (an absolute
XDG_CONFIG_HOME, else ~/.config) when it exists, and the defaults below
otherwise. serve needs --settings or PATCHULA_SETTINGS. A run on a server
uses the server’s settings and never reads the local file; --settings keeps a
run on this machine and cannot be combined with --remote.
amends "PatchulaSettings.pkl"
concurrency = 4http { hostConcurrency { ["api.github.com"] = 8 }}server { allowedInstallations { 123456 }}Shared
Section titled “Shared”| Field | Type | Default | Meaning |
|---|---|---|---|
concurrency |
Int |
8 |
repositories scanned at once, 1 to 100; --concurrency wins in the CLI |
recheck |
"now"|"next-run"? |
null |
checkbox wording; null is now in the server and next-run in the CLI; --recheck and PATCHULA_RECHECK win |
http.defaultHostConcurrency |
Int |
32 |
HTTP requests in flight per host, 1 to 100 |
http.hostConcurrency |
Mapping<String, Int> |
none | per-host overrides, keyed by lowercase hostname |
http.registryFreshnessSecs |
Int |
3600 |
freshness floor for OCI tag lists without validators; 0 uses upstream policy |
http.goFreshnessSecs |
Int |
3600 |
freshness floor for Go proxy lists and @latest; 0 uses upstream policy |
http.advisoryFreshnessSecs |
Int |
3600 |
freshness floor for OSV advisory listings; 0 asks OSV on every run |
github.writeBurst |
Int |
12 |
writes that go out unpaced before pacing to one a second, 1 to 19, so a minute holds at most writeBurst + 60 writes; a secondary-rate-limit answer paces writes at one a second for an hour |
registries |
Mapping<String, Registry> |
none | private registry credentials, keyed by https URL prefix |
lockfiles.cacheGiB |
Int |
20 |
GiB of package caches lockfile tools share between runs, 1 to 1000000; least recently used private partitions go first, public last |
The server builds each installation’s HTTP clients from http and its
registry credentials, and rebuilds them when either changes. Its GitHub client
keeps 4 requests in flight unless http.hostConcurrency sets api.github.com;
the CLI uses the host limit, 16 by default.
Registries
Section titled “Registries”A registries key is an https URL prefix without a user, query or fragment.
| Field | Type | Default | Meaning |
|---|---|---|---|
auth |
("basic"|"bearer")? |
null |
basic sends username and the secret, exchanging them at a container registry’s token service; bearer sends the secret as a token; null sends nothing |
username |
String? |
null |
required for basic, without a colon; refused otherwise |
secret |
Secret? |
null |
required with auth, refused without it |
secret.env |
String? |
null |
environment variable holding the secret |
secret.file |
String? |
null |
file holding the secret |
mirrorOf |
String? |
null |
a public registry’s https URL prefix this entry stands in for |
allowedInstallations |
Listing<Int> |
all | server only: installations that may use the entry |
tools |
Boolean |
false |
also give the credentials to lockfile tools, which run repository and package code, so any repository the Count processes can read them; needs auth, not for a mirror, no other entry may sit under its prefix, and the prefix cannot hold = or ; |
An entry needs auth, mirrorOf or both. Set exactly one of secret.env and
secret.file. Trailing line breaks are dropped from either source. The
settings file names where a secret lives, never the secret.
Versions found with credentials show like any others, in a public repository’s dependency dashboard, pull requests and the server’s repository API. The API stores a private repository’s run without them, so they do not appear if it later becomes public. Whether a lookup sent credentials, to an entry’s own registry or through a mirror, from the network or the cache, is recorded as its requests are made, for every source.
Server
Section titled “Server”| Field | Type | Default | Meaning |
|---|---|---|---|
triggers |
Triggers |
all on | which events start a batch |
sweepCron |
String? |
"0 0 * * * *" |
six-field cron with seconds; null turns sweeps off |
sweepTimezone |
String |
"UTC" |
IANA timezone for the sweep |
batchSize |
Int |
32 |
queue entries per batch, 1 to 1000 |
coalescingMs |
Int |
1000 |
how long the first event waits for related events, 0 to 60000 |
workers |
Int |
4 |
installations whose batches run at once, 1 to 64, each one batch at a time; read at start. Each runs its own lockfile tools, so lower it on a small host |
reportDirectory |
String? |
null |
write each report to a file here instead of logging it |
reportsKept |
Int |
200 |
reports reportDirectory keeps, 1 to 100000; the oldest are deleted after each new one |
allowedInstallations |
Listing<Int> |
any | installation IDs to serve |
allowedRepositories |
Listing<String> |
any | owner/repo names to serve, case-insensitive |
advertise |
Boolean |
true |
hide the server’s URL in PRs and the dashboard, so the CLI in a checkout can offer it |
publicUrl |
String? |
null |
the HTTPS URL to advertise; null uses the App’s webhook URL without its /webhook path |
publicApi |
Boolean |
true |
serve the repository API, which shows anyone what the Count last saw of each public repository |
triggers has push, dashboard, pullRequestEdited, pullRequestClosed,
installation and checks, all true by default.
When both allowlists are set, both must match. Work is filtered when it is accepted and again just before it runs.
The schema
Section titled “The schema”/// Operator settings, read by the CLI and by `patchula serve`. Secrets are/// deliberately absent.module PatchulaSettings
/// Repositories scanned at once, 1 to 100. `--concurrency` overrides it.concurrency: Int = 8/// The checkbox wording. null means `now` in the server and `next-run` in the/// CLI; flags and environment take precedence.recheck: "now" | "next-run"? = nullhttp: Http = new {}github: Github = new {}/// Credentials for private registries, keyed by https URL prefix, such as/// "https://acme.jfrog.io/artifactory/api/helm/charts". A request under a/// prefix, matched by whole path segments, carries that entry's credentials;/// the longest prefix wins.registries: Mapping<String, Registry> = new {}lockfiles: Lockfiles = new {}/// Only `patchula serve` reads this section.server: Server = new {}
class Http { /// HTTP requests in flight per host, 1 to 100. defaultHostConcurrency: Int = 32 /// Per-host overrides of `defaultHostConcurrency`, keyed by lowercase hostname. hostConcurrency: Mapping<String, Int> = new {} /// Freshness seconds for OCI tag lists without validators; 0 uses upstream /// policy. registryFreshnessSecs: Int = 3600 /// Minimum freshness seconds for Go proxy lists and latest; 0 uses upstream /// policy. goFreshnessSecs: Int = 3600 /// Freshness seconds for OSV advisory listings; 0 asks OSV on every run. advisoryFreshnessSecs: Int = 3600}
class Github { /// Writes that go out unpaced before pacing to one a second, 1 to 19, so a /// minute holds at most writeBurst + 60 writes, under GitHub's documented 80. /// A secondary-rate-limit answer paces writes at one a second for an hour. writeBurst: Int = 12}
class Registry { /// `basic` sends `username` and the secret as a password, and exchanges /// them at a container registry's token service; `bearer` sends the secret /// as a bearer token. null sends no credentials, for an open mirror. auth: ("basic" | "bearer")? = null /// Required for `basic`, and refused otherwise. username: String? = null /// Where the secret is read from, never the secret itself. Required with /// `auth`, and refused without it. secret: Secret? = null /// A public registry's https URL prefix that this entry stands in for, such /// as "https://registry.npmjs.org". Requests under it go to this entry's /// prefix instead, with no fallback. Container registries are not mirrored. mirrorOf: String? = null /// Only `patchula serve` reads this: installation IDs that may use the /// entry. Empty allows every installation the server serves. allowedInstallations: Listing<Int> = new {} /// Also give the credentials to lockfile tools. They run repository and /// package code, so any repository the Count processes can read them. /// Needs `auth`; not for a mirror, no other entry may sit under its /// prefix, and the prefix cannot hold `=` or `;`. tools: Boolean = false}
class Lockfiles { /// GiB to keep of the package caches lockfile tools share between runs, /// evicting least recently used private partitions first, then the public /// one. 0 turns the persistent caches off. cacheGiB: Int = 20}
/// Exactly one of `env` and `file`.class Secret { /// An environment variable holding the secret. env: String? = null /// A file holding the secret; trailing line breaks are dropped. file: String? = null}
class Server { triggers: Triggers = new {} sweepCron: String? = "0 0 * * * *" sweepTimezone: String = "UTC" batchSize: Int = 32 coalescingMs: Int = 1000 /// Installations whose batches run at once, each one batch at a time. Read /// at start. workers: Int = 4 /// null emits the versioned report as a structured log event. reportDirectory: String? = null /// Batch reports `reportDirectory` keeps, 1 to 100000; the oldest are /// deleted after each new one. reportsKept: Int = 200 /// Empty lists allow all installations/repositories the App can access. allowedInstallations: Listing<Int> = new {} allowedRepositories: Listing<String> = new {} /// Hide this server's URL in the PRs and dashboard the Count writes, so /// `patchula` in a checkout can offer to run there. advertise: Boolean = true /// The https URL to advertise. null uses the App's webhook URL without its /// /webhook path. publicUrl: String? = null /// Serve /api/v1/repositories, which shows anyone what the Count last saw of /// each public repository he runs. publicApi: Boolean = true}
class Triggers { push: Boolean = true dashboard: Boolean = true pullRequestEdited: Boolean = true pullRequestClosed: Boolean = true installation: Boolean = true checks: Boolean = true}© 2026 Sweepy
