Configuration file

Most repositories need no configuration. Add .github/upseam.yml to the default branch only when you want one of three things:

internal: watch your own OpenAPI or GraphQL contract and send pull requests to the repositories that consume it.
ignore: skip providers or paths.
agent: have your own coding agent write the fixes in your GitHub Actions, see Bring your own agent.

The delivery mode, the model and Slack live on the settings page, not in this file.

internal:
  - spec: api/openapi.yaml
    consumers: [acme/web, acme/mobile]
ignore:
  providers: [twilio]
  paths: [legacy/**, "**/*.test.ts", scripts]

An empty file gives the defaults: no internal contracts and nothing ignored. Upseam rescans a repository when a push to its default branch changes this file.

internal

A list of contracts that this repository publishes.

Field	Type	Rules
`spec`	string, required	Path to the OpenAPI (JSON or YAML) or GraphQL SDL file, relative to the repository root, without patterns. Each path once.
`consumers`	list, required	1 to 10 repositories as `owner/repo`. Names that differ only in case count once.

Consumers must be in the same Upseam installation as the backend. When a push to the default branch changes spec, each affected consumer gets a pull request. See How it works.

ignore

Field	Type	Rules
`providers`	list	Provider ids from the provider list, for example `twilio`.
`paths`	list	Up to 20 patterns. Files under these paths are not scanned.

Patterns in ignore.paths are matched against paths relative to the repository root, with / as the separator:

* matches within one path segment, ? matches one character within a segment, and ** as a whole segment matches any number of segments.
* and ? also match names that start with a dot, as in .gitignore.
A path is ignored when the pattern matches it or one of its parent directories, so scripts ignores everything under scripts/.
A pattern without / matches at the root only: scripts does not ignore src/scripts. Use **/scripts for that.

Patterns are kept small on purpose: at most 128 characters, 16 segments of at most 32 characters, two ** segments, and four * per segment. Negation with !, [], {}, a leading or trailing /, and . or .. segments are errors.

agent

Field	Type	Rules
`runner`	string	`upseam` (default: the model from the settings page), `claude-code`, `codex`, `opencode`, `hermes` or `openclaw`.

hermes and openclaw run in a Docker sandbox, see Hermes Agent and OpenClaw.

Errors

An invalid file stops the scan of that repository until the file is fixed.

Unknown fields and unknown providers are errors. When the name is close to a known one, the error suggests it ("did you mean"); otherwise it lists the allowed names.
Errors in a field name that field, for example internal[0].consumers[2].
Duplicate keys, non-scalar keys and unknown YAML tags are errors; YAML syntax errors give the line instead of a field.
The file may be at most 64 KiB (an oversized file is an error without a field), and lists other than ignore.paths at most 100 items.