docs / configure
Configure a repository
Repository configuration lives in a single file, .conventional-comments.json, on the default branch. You only need to specify what you want to change. Anything you leave out keeps the product default.
The smallest useful configuration
{ "$schema": "https://conventionalcomments.io/schema/v1.json", "version": 1, "mode": "assist" }
The $schema entry is more than metadata. Your editor uses it to autocomplete available settings, show documentation on hover, and flag invalid values such as "enforc" before you commit them.
Three configuration levels
The repository file is only one of three configuration sources. All three are resolved together, in a fixed order.
| Level | Who controls it | What it does |
|---|---|---|
| floor | The organization, through deployment — never through a repository file. | Sets the minimum mode and defines rules that repositories cannot disable. A repository may be stricter, but never more permissive. |
| organization | A shared configuration document fetched from the URL defined by the floor. | Provides the common baseline. Changing mode here takes effect across the organization, including on pull requests that are already open. |
| repository | .conventional-comments.json on the default branch. | Applies local adjustments, such as exempting bots, enabling an optional label, or silencing a diagnostic. |
Today, the extension is the only component that applies the floor, reading it from the browser's enterprise policy. A future platform-level enforcement mechanism could not read that browser policy directly, so it would need another way to receive the same constraint. That mechanism is intentionally left open until Enforce is designed for each platform.
The settings worth knowing
There are twenty-five settings in total. These are the ones that affect behaviour rather than presentation.
| Key | Default | What it controls |
|---|---|---|
| mode | assist | off · assist · warn · enforce. Assist and warn are fully supported by the extension today. Enforce already provides local strict-mode behavior in the browser; the authoritative platform-level merge gate is still on the roadmap. See the adoption guide for details. |
| formatSeverity | warn | Whether malformed comments can cause the check to fail. Most teams leave this unchanged: unresolved blocking points, rather than formatting mistakes, should normally be what prevents a merge. |
| resolverOverrideGroup | empty | Defines who may override a resolution and record a decision. Required before using enforce. When left empty, both escape hatches are unavailable. |
| exemptUsers | empty | Users whose comments are never validated. Values are matched against platform logins case-insensitively. |
| toolCommands | empty | Defines comments intended for bots or tools. See the warning below. |
| labels | 13 labels | Per-label overrides. Only include the labels you want to change. |
| severities | product defaults | Changes the severity of individual diagnostics or silences them entirely. |
| coreMinVersion | 1.0.0 | Requires a minimum core version across the organization. |
toolCommands is empty by default.
In strict mode, a bare /rebase is treated like any other non-conforming comment unless the repository explicitly declares it. Adding "/*" exempts every slash command. Bot accounts are declared individually and must match exactly, for example "@dependabot".
Two behaviours worth knowing
- Unknown settings are ignored with a warning rather than rejected. A recognized setting with an invalid value is different: it invalidates the entire document. If the configuration cannot be interpreted reliably, none of it is applied.
- A
configUrldeclared in the repository file is ignored. The organization configuration URL comes exclusively from the floor. Allowing a repository to redirect it would effectively allow that repository to choose its own organization-wide rules.