# Settings

> Operator settings in PatchulaSettings.pkl, shared by the CLI and patchula serve: concurrency, HTTP limits, and the server's triggers, sweeps and allowed installations.

Operator settings, in a Pkl file that amends the bundled `PatchulaSettings.pkl`. The CLI (`run`, `lookup`, `apply`, `tui`) and [`patchula serve`](https://count-patchula.sweepy.dev/guide/server/) 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`.

```pkl
amends "PatchulaSettings.pkl"

concurrency = 4
http {
  hostConcurrency { ["api.github.com"] = 8 }
}
server {
  allowedInstallations { 123456 }
}
```

## 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](https://count-patchula.sweepy.dev/guide/sources/#private-registries) credentials, keyed by https URL prefix |
| `lockfiles.cacheGiB` | `Int` | `20` | GiB of package caches [lockfile tools](https://count-patchula.sweepy.dev/guide/lockfiles/#tool-caches) 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

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](https://count-patchula.sweepy.dev/guide/sources/#mirrors) |
| `allowedInstallations` | `Listing<Int>` | all | server only: installations that may use the entry |
| `tools` | `Boolean` | `false` | also give the credentials to [lockfile tools](https://count-patchula.sweepy.dev/guide/lockfiles/#private-registries-in-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](https://count-patchula.sweepy.dev/guide/server/#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

| 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](https://count-patchula.sweepy.dev/guide/server/#found-from-a-checkout) |
| `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](https://count-patchula.sweepy.dev/guide/server/#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

`PatchulaSettings.pkl`

```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
}
```
