Appearance
Configuration file
You can keep a repository's review settings in a file called .easymerge.yaml at the root of the repository, next to your code. Settings in the file replace the matching settings on the Repository settings page, key by key, and go through code review like any other change.
The file is optional. Without it, the Repository settings page decides everything.
Plan availability
The basic review settings work on every plan. Instructions, path rules, filters and the other advanced keys require Pro.
Where EasyMerge reads it
- Name and place.
.easymerge.yamlor.easymerge.yml, at the repository root. If both exist,.easymerge.yamlis used and.easymerge.ymlis ignored with a warning. - Which branch. A pull request uses the file on the branch it is merging into (its base branch), as it stands when the review starts. A pull request to
mainfollowsmain's file; a pull request torelease/2.0follows that branch's file. - Changes in a pull request. A pull request that edits the file is still reviewed with the base branch's file. The new values apply after the change is merged. Until then, the EasyMerge Review check run shows a Configuration change table listing what would change. See The check run.
- Changing the base branch. If you point a pull request at a different base branch whose file differs, EasyMerge reviews it again with the new branch's settings.
- Keys you leave out. Any key the file does not set keeps its value from the Repository settings page. A list in the file replaces the whole list from the page; it is not added to it.
A file that cannot be read as YAML is ignored as a whole, and the Repository settings apply. A file with a mistake in one key ignores only that key; the rest still applies.
A starting file
yaml
# yaml-language-server: $schema=https://easymerge.dev/schemas/easymerge-config.v1.json
version: 1
reviews:
enabled: true
auto_review:
on: [opened, synchronize]
exclude:
- "**/fixtures/**"
- "*.snap"
comments:
post_to_github: true
severities: [warning, critical]
max_per_review: 20
summary: trueThe first line is optional. It lets editors such as VS Code (with the YAML extension) check the file and suggest keys as you type.
The easiest way to begin is Export as YAML on the Repository settings page, which writes the settings in effect today as a file. See Exporting your current settings.
Settings keys
These keys match settings that are also on the Repository settings page. While the file sets one, that setting is locked on the page.
| Key | Values | Setting it replaces |
|---|---|---|
version | 1 | |
reviews.enabled | true or false | Enable AI review on Pull Requests |
reviews.auto_review.on | any of opened, synchronize, reopened | Trigger on PR events |
reviews.exclude | a list of globs, up to 200 | Exclude Patterns |
comments.post_to_github | true or false | Post review on GitHub |
comments.severities | any of info, warning, critical | Comment severities |
comments.max_per_review | a whole number from 1 to 100 | Max comments per review |
comments.summary | true or false | Post summary comment |
comments.post_duplicates | true or false | Post duplicate findings to GitHub |
A few details:
versionis optional. Any value other than1makes EasyMerge ignore the whole file.reviews.excludeuses the exclude pattern syntax. It replaces the repository's own pattern list, but the built-in exclusions (lockfiles,node_modules, build output and the rest of the starting list) always stay in force, so you do not need to repeat them.comments.max_per_reviewalso turns the comment limit on.comments.severitiescannot be an empty list. To silence part of the repository, exclude those paths instead.
Skip draft pull requests, Max files per review, Default review profiles and Spec review have no key in the file and stay on the Repository settings page.
Advanced keys
These keys exist only in the file. They need a plan that includes advanced review configuration (Pro). On another plan they are ignored, the file is marked Active with an issue count, and every other key still applies.
| Key | What it does |
|---|---|
language | The language EasyMerge writes its comments and summary in |
reviews.verbosity | How much detail each comment carries: concise, standard or detailed |
reviews.instructions | Guidance for every review of the repository |
reviews.path_instructions | Guidance for files matching particular paths |
reviews.path_rules | Different comment severities or review profiles for particular paths |
reviews.filters | Pull requests that should not be reviewed at all |
Language
| Value | Language |
|---|---|
en | English |
vi | Vietnamese |
ja | Japanese |
ko | Korean |
zh-CN | Simplified Chinese |
zh-TW | Traditional Chinese |
fr | French |
de | German |
es | Spanish |
pt-BR | Brazilian Portuguese |
Code identifiers, file paths and suggested code stay as they are.
Instructions
Tell the reviewer what matters in your codebase: conventions to enforce, areas to focus on, things it should not comment on.
yaml
reviews:
instructions: |
Prioritise security and correctness over style.
Do not comment on import order; the linter handles it.
path_instructions:
- path: "src/api/**"
instructions: |
Every new endpoint needs input validation and a permission check.
- path:
- "**/*.sql"
- "migrations/**"
instructions: Flag migrations that cannot be rolled back.pathtakes one glob or a list of globs, in the exclude pattern syntax.instructionscan be up to 4,000 characters; eachpath_instructionsentry up to 1,000 characters, with up to 25 entries. All instructions together are capped at 12,000 characters; entries past that total are ignored, starting with the last.- Instructions guide what the reviewer looks for and how it phrases findings. They cannot change how EasyMerge posts, which files it reads, or the settings in this file. Lines that look like an attempt to override the reviewer's own rules are flagged as a warning, so you can spot them in review.
- Characters that are invisible in the file (zero-width or direction-control characters, for example) are removed and reported as a warning, so what you read in the file is what the reviewer gets.
Path rules
Path rules change what is posted, or how files are reviewed, for part of the repository. Each rule needs a path and at least one of comment_severities and profiles.
yaml
reviews:
path_rules:
- path: "docs/**"
comment_severities: [critical]
- path: ["src/auth/**", "src/payments/**"]
profiles: [security, deep-review]comment_severitiesreplacescomments.severitiesfor matching files. In the example, documentation changes get inline comments only for critical findings.profilesadds review profiles for matching files, on top of any the pull request already has:deep-review,securityorstyle-only.
Up to 50 rules. When several rules with comment_severities match a file, the last of them in the file wins. Profiles from every matching rule are combined.
Filters
Filters stop EasyMerge reviewing a pull request at all.
yaml
reviews:
filters:
ignore_authors: ["dependabot[bot]", "renovate*"]
ignore_title_keywords: ["WIP", "[skip review]"]
ignore_labels: ["no-review"]
base_branches: ["main", "release/*"]| Key | A pull request is skipped when | Matching |
|---|---|---|
ignore_authors | its author matches an entry | GitHub username; * matches any characters; not case-sensitive |
ignore_title_keywords | its title contains an entry | plain text, not case-sensitive |
ignore_labels | it has a label in the list | the whole label name, not case-sensitive |
base_branches | it targets a branch not in the list | branch globs, such as release/* |
Each list holds up to 50 entries. Leave out base_branches to review pull requests into any branch.
A skipped pull request gets a Review skipped check run naming the filter and the value that matched. When the reason goes away (you remove the label, or edit the title so the keyword no longer appears), EasyMerge reviews the pull request without waiting for a new commit.
On the Repository settings page
The status bar at the top of the AI review tab of the Repository settings page shows the file on the repository's default branch:
| Status | Meaning |
|---|---|
| No file | There is no .easymerge.yaml on the default branch; the settings on the page apply. |
| Active · valid | The file is in use with no problems. |
| Active, with an issue count | The file is in use, but some keys are ignored. The rest of the file still applies. |
| Can’t be parsed | EasyMerge could not parse the file. Nothing from it applies until it is fixed, so the settings on the page apply. |
| Unreadable | EasyMerge could not read the file from GitHub, so the settings on the page apply. |
| Not checked yet | EasyMerge has not read the file for this repository yet. Select Refresh to check now. |
Open the issue count (or Details) to see each problem; select a line number to jump to it in the file.
Every setting the file decides is marked From .easymerge.yaml and cannot be edited on the page; edit the file instead. The advanced keys are shown under Advanced review rules at the end of the Form view, each with a link to the line that sets it. On a plan without advanced review configuration, those keys are marked Ignored · requires Pro.
To read the file itself, switch to the .easymerge.yaml view. It shows the stored file with line numbers, marks the keys that override a setting on the page or exist only in the file, and lists the keys Applied from this file next to the settings that are Not in this file — UI applies. Select a key to highlight its lines.
The status bar reflects the default branch only. A pull request into another branch uses that branch's file, or the saved settings if it has none.
EasyMerge rechecks the file whenever a commit to the default branch changes it. Refresh checks it straight away.
Checking a file before you commit it
Validate YAML opens a box where you can paste the content of a file. EasyMerge checks it as if it were .easymerge.yaml on the default branch and saves nothing. The result shows:
- the status the file would have: Valid, Partially applied or Ignored;
- each problem, with its line number;
- a Changes table comparing each key's Current value with its value After merge.
Exporting your current settings
Export as YAML writes the configuration in effect now as a file you can Copy or Download. Keep only the keys you want to manage in code, then commit the result as .easymerge.yaml at the repository root. Browsers drop the leading dot from a downloaded file name, so rename the download before committing it. The spec review source is not exported; it stays on the settings page.
The check run
While Post review on GitHub is on, the EasyMerge Review check run reports on the file:
- Problems in the file are listed in the summary and shown as annotations on the lines concerned.
- A pull request that changes the file gets a Configuration change table showing each key that would change after merging. This appears even when Post review on GitHub is off.
- A filtered pull request gets a Review skipped check run, for example: Skipped by
.easymerge.yaml(main@ 1a2b3c4):reviews.filters.ignore_labelsmatchedno-review. - A file EasyMerge cannot read (for example, because the app lacks permission) leads to a warning, and the review runs with the Repository settings.
Common problems
| Message or symptom | What to do |
|---|---|
| The file Can’t be parsed | Fix the YAML syntax error on the line shown. Use Validate YAML to check the fix. |
| version … is not supported; use version 1. | Set version: 1, or remove the key. |
| An unknown key warning | Check the spelling against the tables above. A misspelt key is ignored. |
| Both .easymerge.yaml and .easymerge.yml exist; .easymerge.yml is ignored. | Delete one of the two files. |
| Advanced keys are ignored on your plan | Upgrade to a plan with advanced review configuration, or remove those keys. |
| A setting on the page cannot be edited | It is marked From .easymerge.yaml. Change it in the file, or remove the key to manage it on the page again. |
| A change to the file has no effect on a pull request | The pull request uses its base branch's file. Merge the change first. |
See Limits and defaults for every size limit.