Skip to content
Cawdit

Repository configuration

A repository tunes its reviews with the file .cawdit.toml at its root. Every key is optional, and a repository without the file gets the defaults.

Cawdit reads the file, and the rule files it names, from the head of the pull request’s base branch. It never reads them from the pull request itself, so a pull request cannot change how it is reviewed. A change to .cawdit.toml takes effect once it is merged.

The Configuration tab of a repository’s page in the dashboard shows the settings that apply to its default branch, the rule files Cawdit loads and every warning.

Example

[review]
skip_drafts = true
skip_authors = ["renovate-bot"]
wait_for = ["ci/crow/pr/test"]
min_severity = "warning"
max_findings = 20
request_changes = false
fail_at = "error"

[context]
budget = 100000

[paths]
ignore = ["vendor/**", "**/*.pb.go", "web/package-lock.json"]

[rules]
files = ["docs/review/*.md", "CONTRIBUTING.md"]

[review]

Key Type Default Description
review.skip_drafts boolean true Skip draft pull requests. Forgejo marks a pull request as a draft while its title starts with WIP: or [WIP], by default. Cawdit reviews it once the prefix is gone.
review.skip_authors list of logins none Skip pull requests by these authors, compared without regard to case. Use it for bots such as Renovate.
review.wait_for list of status contexts none Review only after each of these commit statuses succeeds, such as ci/crow/pr/test. When one fails, Cawdit skips the commit.
review.min_severity info, warning or error warning The least severe finding Cawdit posts.
review.max_findings integer from 1 to 100 20 The most findings one review posts. Cawdit keeps the most severe ones.
review.request_changes boolean false Give a review with a new error finding the verdict “request changes” instead of “comment”.
review.fail_at info, warning or error error The least severe open finding that makes Cawdit’s commit status fail.

Cawdit never approves a pull request.

The skips apply to automatic reviews. A review that someone asks for, by mentioning Cawdit in a comment, ignores skip_drafts and skip_authors.

Only cawdit serve waits for wait_for. It checks the statuses about once a minute and gives up after an hour, and then skips the commit. In a CI step, order the steps with the CI system instead, such as with depends_on in Crow.

fail_at sets the commit status, which branch protection can require. The fail_on setting of the Crow plugin, or --fail-on of cawdit review, fails the CI step instead.

[context]

Key Type Default Description
context.budget integer from 10000 to 1000000 100000 The most tokens, by Cawdit’s estimate, of code and rules that one review sends to the model.

A larger budget gives the model more of the surrounding code and costs more. When a pull request does not fit, Cawdit first sends less of the code around each change, and then leaves out the files with the largest diffs. The review’s summary names every file it left out.

[paths]

Key Type Default Description
paths.ignore list of globs none Files Cawdit does not review, matched against the path from the repository root.

* matches within one directory and ** matches any number of directories. vendor/** ignores everything below vendor, and **/*.pb.go ignores every file ending in .pb.go.

[rules]

Key Type Default Description
rules.files list of globs none Markdown files with your review rules. Cawdit gives their content to the model with every review.

Write rules the way you would brief a new reviewer, such as “Every SQL query goes through the store package”. Rule files have these limits:

  • A rule file must end in .md and stay inside the repository, so a pattern must not start with / or contain ...
  • Cawdit reads at most 20 rule files, each at most 32 KiB and all together at most 128 KiB.
  • A missing file, a file over a limit, or a pattern that matches nothing is skipped with a warning in Cawdit’s log.

Errors and warnings

The file may be at most 64 KiB. A value of the wrong type or out of range is an error, and the review fails until the file on the base branch is fixed. An unknown key is only a warning, so a newer .cawdit.toml still works with an older Cawdit. Cawdit logs the warnings of each review.