Skip to main content
MergeGuide reads project configuration from a YAML file. Running mergeguide init creates one for you at .mergeguide/config.yaml, along with a sample custom-policy file.

​
Where config lives

MergeGuide looks for configuration in this order:
  1. .mergeguide/config.yaml (project)
  2. .mergeguide.yaml (project, alternate location)
  3. ~/.mergeguide/config.yaml (user-global)

​
The default config

mergeguide init writes this starting configuration:
.mergeguide/config.yaml
version: "1.0"
fail_mode: closed
enforcement_mode: graduated
policies:
  use_defaults: true
  custom_dir: .mergeguide/policies
KeyDescription
versionConfig schema version.
fail_modeclosed blocks on blocking findings; controls how MergeGuide behaves when a check fails.
enforcement_modegraduated applies enforcement progressively across your workflow layers.
policies.use_defaultsWhether to run MergeGuide’s default policy set.
policies.custom_dirDirectory holding your custom policy files.
This page documents the keys created by init. The full configuration-key reference — including every optional key, its type, default, and precedence — is being expanded in Configuration keys. Until that page is complete, treat the keys above as the verified set and add new keys only after confirming them against the running CLI.

​
Custom policies

init also creates a sample custom-policy file at .mergeguide/policies/custom.yaml. Policies in custom_dir are loaded alongside the defaults:
.mergeguide/policies/custom.yaml
version: "1.0"

metadata:
  name: "Custom Policies"
  description: "Project-specific policy rules"

policies:
  - id: "example-rule"
    name: "Example Rule"
    description: "An example custom rule"
    severity: warning
    languages: ["*"]
    enabled: false   # set to true to enable
    rules:
      - pattern: "example_pattern"
        message: "This is an example violation"
        remediation: "Replace with the correct pattern"
You can also pass a policy file directly to a single check: 
mergeguide check src/ --policy ./my-policy.yaml

​
Next steps

Policies & frameworks

Choose which policies and frameworks apply.

Thresholds

Decide what severity blocks a commit or a merge.