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]
| 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
.mdand 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.