otto.yml - Otto

Your workspace settings apply to every repository. To configure a single repository, commit an otto.yml at its root. In it you can:

Set the review depth for the repository and for individual paths
Add review instructions for the repository and for individual paths
Ignore files such as lockfiles, snapshots, and generated code
Skip automatic reviews by label, title, branch, or author
Limit when Otto approves

Without an otto.yml, Otto reviews the repository with your workspace settings.

Quick start

Create otto.yml at the repository root and merge it into your default branch:

otto.yml

version: 1
reviews:
  paths:
    - match: ['src/payments/**']
      depth: max
      instructions: |
        Every money amount must be an integer number of cents.
  ignore: ['**/*.snap']

Pull requests opened after the merge use it. See Which version applies.

Full example

otto.yml

version: 1
reviews:
  # false = no automatic reviews; `/otto review` still works
  enabled: true

  # Repository default depth: standard | deep | max (omit to use the workspace depth)
  depth: deep

  # Applied to every review of this repository
  instructions: |
    Prefer composition over inheritance.

  # Every matching rule contributes its depth and instructions
  paths:
    - match: ['features/**']
      depth: max
      instructions: |
        Verify every new feature is behind a feature flag.
    - match: ['docs/**', '**/*.md']
      depth: standard

  ignore: ['**/*.snap', 'fixtures/**']
  default_ignores: true

  # Automatic reviews only; an explicit `/otto review` always runs
  skip:
    labels: ['no-otto']
    title_contains: ['[skip otto]', 'WIP']
    base_branches: ['release/*']
    head_branches: ['dependabot/**']
    authors: ['renovate[bot]']

  approval:
    approve_up_to: P3

Reference

Field	Type	Default	Description
`version`	number	`1`	Config format version. Only `1` exists.
`reviews.enabled`	boolean	`true`	`false` turns off automatic reviews. `/otto review` still works.
`reviews.depth`	string	(workspace depth)	Default depth for this repository: `standard`, `deep`, or `max`.
`reviews.instructions`	string	(none)	Guidance for every review of this repository.
`reviews.paths`	list	`[]`	Path rules, each with its own `depth` and `instructions`.
`reviews.paths[].match`	string[]	(required)	Globs the rule applies to.
`reviews.paths[].depth`	string	(none)	Depth for files matching the rule.
`reviews.paths[].instructions`	string	(none)	Guidance for files matching the rule.
`reviews.ignore`	string[]	`[]`	Globs Otto leaves out of the review.
`reviews.default_ignores`	boolean	`true`	Also ignore the built-in list of lockfiles, build output, and generated code.
`reviews.skip.labels`	string[]	`[]`	Skip automatic reviews of PRs with any of these labels (case-insensitive).
`reviews.skip.title_contains`	string[]	`[]`	Skip automatic reviews of PRs whose title contains any of these (case-insensitive).
`reviews.skip.base_branches`	string[]	`[]`	Skip automatic reviews of PRs into a branch matching any of these globs.
`reviews.skip.head_branches`	string[]	`[]`	Skip automatic reviews of PRs from a branch matching any of these globs.
`reviews.skip.authors`	string[]	`[]`	Skip automatic reviews of PRs by these authors (GitHub login or Azure unique name, case-insensitive).
`reviews.approval.approve_up_to`	string	`P3`	The most severe finding Otto may still approve with: `P3`, `P2`, or `none`.

Any field that takes a list also accepts a single string, so ignore: '**/*.snap' works too.

Limits

Limit	Value
File size	64 KB
Rules in `reviews.paths`	50
Entries in any one list (globs, labels, …)	100
Length of one glob	512 characters
Length of one skip value (label, title, author)	256 characters
Length of any `instructions`	4,000 characters

List entries past a limit are ignored, and the rest of the list still applies. An instructions value over 4,000 characters is ignored entirely, not truncated. Each is reported as an error.

Where Otto looks

Otto reads otto.yml from the repository root. It also accepts otto.yaml; if both exist, otto.yml wins. The file must be a regular file, not a symlink.

Which version applies

Otto reads otto.yml from the pull request’s base commit: the merge-base of the PR branch and its target branch. It never reads the PR’s own copy, so a pull request can’t change how it is itself reviewed. A PR that sets enabled: false or lowers depth is still reviewed with the configuration it started from. After you merge an otto.yml change into the target branch, it applies to:

New pull requests.
Existing pull requests once they are rebased onto, or merge in, the updated target branch.

To try a change, merge it and open a test PR. Changing otto.yml inside an open PR has no effect on that PR.

Globs

Globs in paths, ignore, and the branch skip rules match the file’s full path from the repository root:

Glob	Matches
`fixtures/**`	Everything under the top-level `fixtures` directory only
`/fixtures/`	Everything under any `fixtures` directory, at any depth
`*/.snap`	Snapshot files anywhere
`*.md`	Markdown files in the repository root only
`.github/**`	Dotfiles and dot-directories match like any other path
`src/{api,web}/**`	Everything under `src/api` or `src/web`

* stays inside one path segment; ** crosses segments. For branches, globs match the branch name without refs/heads/, so release/* matches release/1.2 but not release/1.2/hotfix.

YAML notes

Otto parses otto.yml with strict, JSON-compatible YAML:

Booleans are only true and false. yes, no, on, and off are strings, so enabled: no is an error and the default (true) applies.
Quote globs that start with *, {, or [, which YAML would otherwise treat as syntax: ignore: ['**/*.snap'].
Use | for multi-line instructions.

Errors

A broken otto.yml never stops a review. Otto ignores each invalid or unknown part, keeps the rest, and uses your workspace settings for anything it ignored:

An invalid value (for example depth: maximum) is ignored, and that field falls back to its default.
An invalid entry in a list is dropped on its own; the rest of the list still applies.
A path rule without any valid match glob is ignored.
An unknown key is ignored.
If the file isn’t valid YAML, is larger than 64 KB, or can’t be read, Otto reviews with your workspace settings only.

On GitHub, the Otto Review check summary lists the problems Otto found (up to 10, with a count of the rest), so you can fix the file.

​Quick start

​Full example

​Reference

​Limits

​Where Otto looks

​Which version applies

​Globs

​YAML notes

​Errors

Quick start

Full example

Reference

Limits

Where Otto looks

Which version applies

Globs

YAML notes

Errors