Skip to content

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 = 4
http {
hostConcurrency { ["api.github.com"] = 8 }
}
server {
allowedInstallations { 123456 }
}
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.

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.

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.

PatchulaSettings.pkl
/// 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"? = null
http: 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
}