# Repository configuration

> Configure reviews per directory with .mergeharbor/ folders: settings, plain-language rules and context files that cascade from the root, with org locks.

MergeHarbor reads configuration from the repository itself, so review settings live next to the code they govern and change through pull requests like anything else.

## Files

```
.mergeharbor.yml                       # root settings (optional)
.mergeharbor/rules.md                  # rules for the whole repository
services/payments/.mergeharbor/
  config.yml                           # settings for services/payments/**
  rules.md                             # rules for services/payments/**
  context.yml                          # files always given to the reviewer
```

Every file is optional. A `.mergeharbor/` folder can sit in any directory and applies to everything below it.

## Precedence

Lowest first; later layers override only the fields they set:

1. MergeHarbor defaults
2. Organization settings (console)
3. Repository settings (console)
4. Root configuration: `.mergeharbor.yml`, then `.mergeharbor/config.yml`
5. Deeper `.mergeharbor/` folders, from the root down — **the closest folder to a file wins**

**Locked settings** are the exception: when an organization admin locks a setting in **Repositories → Configuration files**, the organization's value always applies. Repository settings cannot set it, and a configuration file that sets it gets a note in the review's configuration check. Locking settings is part of the Enterprise plan.

Files are read from the pull request's merge base. A pull request cannot change its own review; configuration changes apply once they merge.

## config.yml

`config.yml` uses the same keys as [`.mergeharbor.yml`](https://mergeharbor.com/docs/configuration), plus three of its own:

```yaml
# yaml-language-server: $schema=https://mergeharbor.com/schema/config.json
tier: deep # standard | deep | max
min_severity: major
categories: [security, correctness, data_integrity]
ignore_paths: [fixtures/**, "*.snap"]
instructions: Amounts are integers in cents. Flag any floating-point money.
rules:
  - Every charge takes an idempotency key.
  - { rule: "Use the ledger package for balance changes", paths: ["**/*.go"], severity: major }
context: [docs/ledger.md, /docs/architecture.md]
```

How each setting combines across folders:

| Setting                                                                   | How it applies                                                                                              |
| ------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------- |
| `min_severity`, `categories`, `checks.disable`                            | Per file: the closest folder wins.                                                                          |
| `depth`, `strictness`, `tier`                                             | Per pull request: the strongest value requested by any changed file's folder.                               |
| `ignore_paths`                                                            | Adds to the inherited patterns. Patterns are relative to the folder.                                        |
| `instructions`                                                            | In a nested folder, becomes a rule for the files under it.                                                  |
| `rules`, `context`                                                        | Apply to files under the folder. Paths are relative to the folder; a leading `/` means the repository root. |
| Everything else (`trigger`, `filters`, `max_comments`, `status_check`, …) | Root configuration only. Set in a nested folder, it is reported and ignored.                                |

## rules.md

Write rules in plain English. Each heading starts a rule; without headings, each top-level bullet is a rule; a file with neither is one rule. Text before the first heading or bullet is treated as an introduction.

```markdown
Rules for the payments service.

- Every charge takes an idempotency key.
- Never log card numbers, even masked.
```

A folder's rules are only sent to the reviewer when a pull request changes files under that folder.

## context.yml

Files the reviewer always reads (up to 20, such as design notes or API contracts), background notes, and other repositories it may consult. The same keys work under `context:` in `config.yml`.

```yaml
files:
  - docs/ledger.md
  - { path: /proto/payments/*.proto, reason: API contract, paths: ["api/**"] }
notes:
  - { note: "Legacy module: keep changes minimal.", paths: ["legacy/**"] }
repos: [acme/shared-lib]
```

A file or note with `paths` is used only when the pull request changes matching files. Notes are background for the reviewer, not rules to enforce.

## Turning off an inherited rule

Give a rule an `id`, then list it under `disable_rules` in a deeper folder:

```yaml
# .mergeharbor/config.yml
rules:
  - { id: tests-required, rule: "New behavior comes with tests." }

# prototypes/.mergeharbor/config.yml
disable_rules: [tests-required]
```

## Checking your configuration

- Every review summary has a **Configuration check** section when a file has problems: the file, the line, and what was skipped.
- `mh config check` validates every configuration file in your working tree, and `mh config explain <path>` prints the effective settings for a file with the source of each value. See [CLI](https://mergeharbor.com/docs/cli).
- **Repositories → Configuration files** in the console shows the effective configuration for any path in a connected repository.
- The JSON schemas at [`/schema/config.json`](https://mergeharbor.com/schema/config.json) and [`/schema/context.json`](https://mergeharbor.com/schema/context.json) give editors completion and validation.

## Moving from another reviewer

`mh import` converts configuration left by another AI code reviewer into `.mergeharbor/` folders. See [Import existing review configuration](https://mergeharbor.com/docs/import-config).