Configuration file

View as Markdown

Every key a repository's .proofline.yaml accepts, with its type, limits and allowed values, generated from the file's published JSON Schema.

Commit the file as .proofline.yaml or .proofline.yml at the repository root, and keep only one. Each pull request review reads the file at the pull request's merge base, so a pull request cannot change the configuration of its own review; its edits apply after it merges. A review of local changes reads the file at the patch's base commit in the same way.

Version 2 accepts every version 1 file unchanged. The effort key is deprecated: it stays valid so existing files keep working, and Proofline ignores its value.

Validate in your editor#

The schema is published at https://proofline.sh/api/schemas/repository-config-v2.json. Editors that use the YAML language server validate and complete the file when its first line names the schema:

# yaml-language-server: $schema=https://proofline.sh/api/schemas/repository-config-v2.json
version: 2

To check a draft against what Proofline reads, paste it into the repository's Settings → Config file page, as Review repository configuration describes.

Keys#

architecture#

KeyTypeRequiredDescription
architectureobjectno
architecture.layersarray of objectyes1 to 50 items.
architecture.layers[].namestringyes
architecture.layers[].pathsarray of stringyes1 to 20 items.
architecture.rulesarray of object or nullnoAt most 100 items.
architecture.rules[].forbidden_packagesarray of stringnoExternal packages as code imports them, such as sqlx, requests, @aws-sdk/client-s3 or github.com/jackc/pgx.
architecture.rules[].idstringyes
architecture.rules[].layerstringyes
architecture.rules[].may_depend_onarray of stringnoThe only other layers this layer may depend on. Absent places no limit; empty allows none.
architecture.rules[].must_not_depend_onarray of stringno
architecture.rules[].severitystringyesOne of error, warning. error: Every new violation is placed inline by the publication floor. warning: New violations follow the code lane's ordinary placement.

checks#

KeyTypeRequiredDescription
checksarray of object or nullnoPre-merge checks, each reported as its own GitHub Check. A review evaluates the checks its merge base defines, so a pull request cannot remove its own. At most 20 items.
checks[].decidabilitystring or nullnoOne of METADATA_ONLY, CODE_REQUIRED, EXTERNAL_CONTEXT_REQUIRED. METADATA_ONLY: The title, description and changed paths settle it. CODE_REQUIRED: The changed code settles it. EXTERNAL_CONTEXT_REQUIRED: Only an issue tracker or a document settles it. A check reads neither, so the check is undecided.
checks[].instructionsstring or nullno
checks[].modestringyesOne of ADVISORY, BLOCKING. ADVISORY: Concludes neutral whatever the verdict. BLOCKING: Concludes success only when the check is met.
checks[].path_globsarray of string or nullno
checks[].patternstring or nullno
checks[].required_labelsarray of string or nullno
checks[].rulestringyesTITLE_PATTERN, DESCRIPTION_PRESENT, LINKED_ISSUE, REQUIRED_LABELS or NATURAL_LANGUAGE. A COVERAGE check is defined in settings. One of TITLE_PATTERN, DESCRIPTION_PRESENT, LINKED_ISSUE, REQUIRED_LABELS, NATURAL_LANGUAGE.
checks[].slugstringyesThe check's name; GitHub shows it as Proofline check / <slug>.

effort#

KeyTypeRequiredDescription
effortany JSON valuenoDeprecated. Retired. The key is accepted so existing files stay valid, and its value is ignored: Proofline chooses each review's depth, and the deep review command raises it for one pull request. Remove the key. Historical snapshots keep its value so their digests still verify.

guidance#

KeyTypeRequiredDescription
guidancestring or nullnoAt most 12,000 characters.

reviews#

KeyTypeRequiredDescription
reviewsobjectnoThe file's review scope. Its path keys replace the console's setting, key by key, and an empty list clears that filter. Its branch and label keys only add a restriction: the console's branch and label filters decide an automatic review before the file is read, so a pull request must pass both, and an empty list restricts nothing. A present key holds a value: the parser refuses an empty one, and the published schema says so.
reviews.base_branchesarray of stringnoAdds a restriction: review only pull requests into a branch that matches one of these globs and that the console's filter also admits. At most 128 items.
reviews.exclude_generatedbooleannoReplaces the console's choice to skip generated files.
reviews.labels_excludearray of stringnoAdds a restriction: skip pull requests that carry one of these labels, as well as those the console's filter skips. At most 128 items.
reviews.labels_includearray of stringnoAdds a restriction: review only pull requests that carry one of these labels and that the console's filter also admits. At most 128 items.
reviews.paths_excludearray of stringnoReplaces the console's excluded paths. An empty list excludes none. At most 128 items.
reviews.paths_includearray of stringnoReplaces the console's included paths. An empty list reviews every path. At most 128 items.

rules#

KeyTypeRequiredDescription
rulesarray of object or nullnoAt most 100 items.
rules[].applicabilitystring or nullnoOmitted, the rule resolves from its conditions. A configuration snapshot retained before this field omits it and keeps its digest. One of ALWAYS, AUTO.
rules[].keystringyesMatches ^[a-z][a-z0-9-]{2,63}$.
rules[].languagesarray of string or nullno
rules[].modestringnoOne of APPLY, DISABLED. Default APPLY.
rules[].path_globsarray of string or nullnoAt most 20 items.
rules[].textstring or nullnoAt most 2,000 characters.

strictness#

KeyTypeRequiredDescription
strictnessstringnoHow readily a finding becomes an inline comment in reviews of this repository. It replaces the repository's and the organization's strictness and their inline limits for a review that reads it. One of LOW, DEFAULT, HIGH. LOW: Fewer inline comments: a default ceiling of 5 per review. DEFAULT: A default ceiling of 10 inline comments per review. HIGH: More inline comments: a default ceiling of 20 per review.

version#

KeyTypeRequiredDescription
versioninteger (uint8)yes1 to 2.