Skip to content

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.yaml or .easymerge.yml, at the repository root. If both exist, .easymerge.yaml is used and .easymerge.yml is 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 main follows main's file; a pull request to release/2.0 follows 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: true

The 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.

KeyValuesSetting it replaces
version1
reviews.enabledtrue or falseEnable AI review on Pull Requests
reviews.auto_review.onany of opened, synchronize, reopenedTrigger on PR events
reviews.excludea list of globs, up to 200Exclude Patterns
comments.post_to_githubtrue or falsePost review on GitHub
comments.severitiesany of info, warning, criticalComment severities
comments.max_per_reviewa whole number from 1 to 100Max comments per review
comments.summarytrue or falsePost summary comment
comments.post_duplicatestrue or falsePost duplicate findings to GitHub

A few details:

  • version is optional. Any value other than 1 makes EasyMerge ignore the whole file.
  • reviews.exclude uses 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_review also turns the comment limit on.
  • comments.severities cannot 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.

KeyWhat it does
languageThe language EasyMerge writes its comments and summary in
reviews.verbosityHow much detail each comment carries: concise, standard or detailed
reviews.instructionsGuidance for every review of the repository
reviews.path_instructionsGuidance for files matching particular paths
reviews.path_rulesDifferent comment severities or review profiles for particular paths
reviews.filtersPull requests that should not be reviewed at all

Language ​

ValueLanguage
enEnglish
viVietnamese
jaJapanese
koKorean
zh-CNSimplified Chinese
zh-TWTraditional Chinese
frFrench
deGerman
esSpanish
pt-BRBrazilian 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.
  • path takes one glob or a list of globs, in the exclude pattern syntax.
  • instructions can be up to 4,000 characters; each path_instructions entry 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_severities replaces comments.severities for matching files. In the example, documentation changes get inline comments only for critical findings.
  • profiles adds review profiles for matching files, on top of any the pull request already has: deep-review, security or style-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/*"]
KeyA pull request is skipped whenMatching
ignore_authorsits author matches an entryGitHub username; * matches any characters; not case-sensitive
ignore_title_keywordsits title contains an entryplain text, not case-sensitive
ignore_labelsit has a label in the listthe whole label name, not case-sensitive
base_branchesit targets a branch not in the listbranch 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:

StatusMeaning
No fileThere is no .easymerge.yaml on the default branch; the settings on the page apply.
Active · validThe file is in use with no problems.
Active, with an issue countThe file is in use, but some keys are ignored. The rest of the file still applies.
Can’t be parsedEasyMerge could not parse the file. Nothing from it applies until it is fixed, so the settings on the page apply.
UnreadableEasyMerge could not read the file from GitHub, so the settings on the page apply.
Not checked yetEasyMerge 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_labels matched no-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 symptomWhat to do
The file Can’t be parsedFix 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 warningCheck 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 planUpgrade to a plan with advanced review configuration, or remove those keys.
A setting on the page cannot be editedIt 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 requestThe pull request uses its base branch's file. Merge the change first.

See Limits and defaults for every size limit.