Config File (.solemly.yaml)

A .solemly.yaml at the root of a repository keeps its review settings in git, next to the code. Use it to skip automatic reviews of bot pull requests, keep generated files out of reviews, give extra instructions for parts of the codebase, and set how strict reviews are.

Every key is optional. A repository without the file reviews exactly as before. The same rules can be set without a file, in Repository Settings under Review rules. When both exist, the file wins key by key.

Example#

# .solemly.yaml, at the repository root. Every key is optional.
version: 1

reviews:
  # When to review. Read from the base branch.
  trigger: once              # push | once | manual (the "Review when" setting)
  auto_review:
    forks: false             # pull requests from forks; off by default to protect private context and quota
    exclude_authors:         # author logins, case-insensitive; * and ? are wildcards
      - "dependabot[bot]"
      - "renovate[bot]"
      - "*[bot]"
    exclude_branches:        # the branch the change comes from
      - "release/*"
    base_branches:           # if set, only changes into these branches are reviewed
      - main
      - "release/*"
    ignore_title_keywords:   # skipped when the title contains one, case-insensitive
      - "WIP"
      - "[skip review]"
    skip_labels:             # GitHub and GitLab
      - no-review

  # What to review.
  skip_paths:                # globs, like .gitignore; never reviewed, never sent to the model
    - "**/*.lock"
    - "vendor/**"
    - "src/gen/**"

  path_instructions:         # can also come from the pull request itself
    - path: "api/**/*.py"
      instructions: |
        Every new route needs an integration test in tests/api/.
        Flag any SQL built with f-strings.
    - path: "migrations/**"
      instructions: "Migrations must be backward compatible: no column drops or renames."

  # How strict to be. Read from the base branch.
  profile: default           # quiet | default | assertive
  min_severity: MEDIUM       # LOW | MEDIUM | HIGH | CRITICAL; findings below aren't posted
  max_nits: 5                # at most this many LOW findings per review
  block_on: [CRITICAL, HIGH] # severities that fail the Solemly / Review check
  deep_review: auto          # auto | always | never

summary:
  enabled: true              # write the PR summary

Keys#

An explicit min_severity or max_nits wins over the profile.

If block_on lists a severity below min_severity, findings at that severity aren't posted, so they can't block either.

checks, language, tone and linked_repos are reserved for features that aren't available yet. They're accepted and ignored.

Globs#

skip_paths and path_instructions use .gitignore-style globs:

• ** matches across folders, * and ? stay within one folder.
• A pattern without a /, such as *.min.js, matches a file or folder name at any depth.
• A pattern with a /, such as src/gen/**, starts at the repository root.
• Braces such as {a,b} aren't supported. Write one entry per pattern instead.

Authors, branches and labels are matched case-insensitively. * and ? are wildcards there, and brackets are literal, so dependabot[bot] matches the Dependabot login.

Which branch the file is read from#

The file is read from the pull request's base branch, the branch it merges into, for every key except path_instructions. A pull request can't switch off or weaken its own review by editing .solemly.yaml. A change to those keys takes effect once it's merged.

path_instructions are read from the pull request itself when it has them, so you can try new instructions in the pull request that adds them. Otherwise the base branch's apply.

When a pull request is skipped#

A pull request skipped by auto_review gets a neutral check that names the reason, for example Skipped: author dependabot[bot] is excluded by .solemly.yaml. On GitLab and Bitbucket the status reads the reason. Skipped pull requests don't count toward your review quota.

To review one anyway, comment @solemly review, or use Review now on the dashboard. The filters only stop automatic reviews.

Some provider details:

• Forks. Pull requests opened from forks are skipped automatically (Skipped: this pull request comes from a fork, so it isn't reviewed automatically.) unless reviews.auto_review.forks: true is configured on the base branch.
• Labels. GitHub doesn't send a review event when a label is added, so a new label applies from the next push. Bitbucket Cloud has no pull request labels, so skip_labels doesn't apply there.
• GitLab authors. Match on the author's username. Renovate on GitLab is an ordinary user account, so add its username.

When the file is invalid#

If the file isn't valid YAML, or has a key Solemly doesn't know, Solemly posts one comment on the pull request that names the problem. The review then runs with the repository's dashboard settings. Later pushes update that same comment, and once the file is fixed the comment says so. An invalid file never fails or blocks a review.