@dispatch-triage/config

Schema, layered loader, and validator for .github/dispatch.yml.

Part of Dispatch Triage — programmable triage for GitHub. Imported by every surface that has to read a maintainer's configuration.

npm i @dispatch-triage/config

Config is the maintainer's half of Dispatch. Nothing the bot does should surprise someone who has read this file, so validation is generous with warnings and specific about locations.

const result = loadConfig({
  org:  { file: '.github/dispatch.yml (org)', text: orgYaml },
  repo: { file: '.github/dispatch.yml',       text: repoYaml },
  evaluator,                       // optional: catches unparseable expressions
  knownTemplates: new Set([...]),  // optional: catches missing templates
});

Errors and warnings

Severity is chosen by what the maintainer can do about it:

• error — the rule can never work as written. An expression that references a question that does not exist, a duplicate rule id, auto below suggest, an empty then, a named template that is not in the pack.
• warning — the config is valid and will run, but something will not happen. A destructive op that is not in allowDestructive (so it will always be suppressed), a label outside any taxonomy dimension, a rule asking an issue-only question on a pull request trigger.

The distinction matters: the plan's own sample config triggers several warnings on purpose — it plans close actions without opting into close. Refusing to load that would be wrong. Telling the maintainer it will be suppressed is the useful thing.

Every issue carries a file, line, and column traced back through the YAML document, and formatIssue renders it in the form editors turn into a clickable link:

.github/dispatch.yml:14:3  error  auto (0.5) is below suggest (0.9). (rules[3].confidence)
    It makes no sense to apply an action you would not have been willing to propose.

Locations resolve to the key, not the value, so an error about confidence puts the caret on confidence: rather than on whatever happens to be its first field.

Layering

Organisation defaults from the .github repository are applied first, then the repository's own file:

• Objects merge per key, so a repository can raise confidence.auto without restating confidence.suggest.
• Ordinary arrays replace.
• rules concatenate, organisation first, so a repository adds to house policy instead of silently discarding it.
• A rule id appearing in both layers is an error. "Which one won?" is not a question a maintainer should have to ask.

configHash

configHash is sha256 over the canonical JSON of the resolved config, so reformatting the YAML or reordering keys does not change it. It is part of every decision key, which means editing a rule naturally re-triages affected items rather than serving decisions made under the old policy.

JSON Schema

configJsonSchema() emits a JSON Schema for editor completion and for generating the config reference in the docs. zod 4 produces it natively — there is no zod-to-json-schema dependency.

Configuration reference · Documentation · Repository

MIT