> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mergeguide.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Configuration file

> Configure MergeGuide for a project with a .mergeguide/config.yaml file.

MergeGuide reads project configuration from a YAML file. Running
[`mergeguide init`](/get-started/quickstart) 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:

```yaml .mergeguide/config.yaml theme={null}
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.                                               |

<Note>
  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](/reference/config-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.
</Note>

## Custom policies

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

```yaml .mergeguide/policies/custom.yaml theme={null}
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:

```bash theme={null}
mergeguide check src/ --policy ./my-policy.yaml
```

## Next steps

<CardGroup cols={2}>
  <Card title="Policies & frameworks" icon="list-check" href="/configuration/policies-and-frameworks">
    Choose which policies and frameworks apply.
  </Card>

  <Card title="Thresholds" icon="gauge" href="/configuration/thresholds">
    Decide what severity blocks a commit or a merge.
  </Card>
</CardGroup>