Configuration file

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:

.mergeguide/config.yaml (project)
.mergeguide.yaml (project, alternate location)
~/.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

Key	Description
`version`	Config schema version.
`fail_mode`	`closed` blocks on blocking findings; controls how MergeGuide behaves when a check fails.
`enforcement_mode`	`graduated` applies enforcement progressively across your workflow layers.
`policies.use_defaults`	Whether to run MergeGuide’s default policy set.
`policies.custom_dir`	Directory 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

Get started

Provisioning & account

Setup & installation

Configuration

Operation

Navigation

Integrations & CI/CD

Compliance

Methodology

Troubleshooting & FAQ

Reference

Where config lives

The default config

Custom policies

Next steps

Policies & frameworks

Thresholds

​Where config lives

​The default config

​Custom policies

​Next steps

Policies & frameworks

Thresholds

Where config lives

The default config

Custom policies

Next steps