# Configuration file

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
# 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](/help/repository-configuration/#validate-a-draft) describes.

## Keys

### `architecture`

| Key | Type | Required | Description |
| --- | --- | --- | --- |
| `architecture` | object | no |  |
| `architecture.layers` | array of object | yes | 1 to 50 items. |
| `architecture.layers[].name` | string | yes |  |
| `architecture.layers[].paths` | array of string | yes | 1 to 20 items. |
| `architecture.rules` | array of object or null | no | At most 100 items. |
| `architecture.rules[].forbidden_packages` | array of string | no | External packages as code imports them, such as `sqlx`, `requests`, `@aws-sdk/client-s3` or `github.com/jackc/pgx`. |
| `architecture.rules[].id` | string | yes |  |
| `architecture.rules[].layer` | string | yes |  |
| `architecture.rules[].may_depend_on` | array of string | no | The only other layers this layer may depend on. Absent places no limit; empty allows none. |
| `architecture.rules[].must_not_depend_on` | array of string | no |  |
| `architecture.rules[].severity` | string | yes | One 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`

| Key | Type | Required | Description |
| --- | --- | --- | --- |
| `checks` | array of object or null | no | Pre-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[].decidability` | string or null | no | One 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[].instructions` | string or null | no |  |
| `checks[].mode` | string | yes | One of `ADVISORY`, `BLOCKING`. `ADVISORY`: Concludes `neutral` whatever the verdict. `BLOCKING`: Concludes `success` only when the check is met. |
| `checks[].path_globs` | array of string or null | no |  |
| `checks[].pattern` | string or null | no |  |
| `checks[].required_labels` | array of string or null | no |  |
| `checks[].rule` | string | yes | `TITLE_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[].slug` | string | yes | The check's name; GitHub shows it as `Proofline check / <slug>`. |

### `effort`

| Key | Type | Required | Description |
| --- | --- | --- | --- |
| `effort` | any JSON value | no | Deprecated. 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`

| Key | Type | Required | Description |
| --- | --- | --- | --- |
| `guidance` | string or null | no | At most 12,000 characters. |

### `reviews`

| Key | Type | Required | Description |
| --- | --- | --- | --- |
| `reviews` | object | no | The 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_branches` | array of string | no | Adds 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_generated` | boolean | no | Replaces the console's choice to skip generated files. |
| `reviews.labels_exclude` | array of string | no | Adds 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_include` | array of string | no | Adds 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_exclude` | array of string | no | Replaces the console's excluded paths. An empty list excludes none. At most 128 items. |
| `reviews.paths_include` | array of string | no | Replaces the console's included paths. An empty list reviews every path. At most 128 items. |

### `rules`

| Key | Type | Required | Description |
| --- | --- | --- | --- |
| `rules` | array of object or null | no | At most 100 items. |
| `rules[].applicability` | string or null | no | Omitted, the rule resolves from its conditions. A configuration snapshot retained before this field omits it and keeps its digest. One of `ALWAYS`, `AUTO`. |
| `rules[].key` | string | yes | Matches `^[a-z][a-z0-9-]{2,63}$`. |
| `rules[].languages` | array of string or null | no |  |
| `rules[].mode` | string | no | One of `APPLY`, `DISABLED`. Default `APPLY`. |
| `rules[].path_globs` | array of string or null | no | At most 20 items. |
| `rules[].text` | string or null | no | At most 2,000 characters. |

### `strictness`

| Key | Type | Required | Description |
| --- | --- | --- | --- |
| `strictness` | string | no | How 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`

| Key | Type | Required | Description |
| --- | --- | --- | --- |
| `version` | integer (uint8) | yes | 1 to 2. |
