# How to Configure Repository-Specific Settings for no-mistakes

> Learn to configure repository-specific settings for no-mistakes. Create a .no-mistakes.yaml file to define trusted commands policies and more, merging with global defaults for tailored automation.

- Repository: [Kun Chen/no-mistakes](https://github.com/kunchenguid/no-mistakes)
- Tags: how-to-guide
- Published: 2026-07-21

---

**To configure repository-specific settings for no-mistakes, create a [`.no-mistakes.yaml`](https://github.com/kunchenguid/no-mistakes/blob/main/.no-mistakes.yaml) file in your repository root that defines trusted commands, pipeline steps, and auto-fix policies, which the daemon merges with global defaults at runtime.**

The `no-mistakes` tool from the `kunchenguid/no-mistakes` repository uses a per-repository configuration system that balances flexibility with security. By placing a [`.no-mistakes.yaml`](https://github.com/kunchenguid/no-mistakes/blob/main/.no-mistakes.yaml) file at the root of your Git repository, you can override global defaults, customize pipeline gates, and control automated fixes while maintaining strict trust boundaries for executable commands.

## The [`.no-mistakes.yaml`](https://github.com/kunchenguid/no-mistakes/blob/main/.no-mistakes.yaml) Configuration File

The repository-specific configuration lives in [`.no-mistakes.yaml`](https://github.com/kunchenguid/no-mistakes/blob/main/.no-mistakes.yaml) at the repository root. This file is read by both the CLI when starting a run ([`internal/cli/daemon_cmd.go`](https://github.com/kunchenguid/no-mistakes/blob/main/internal/cli/daemon_cmd.go)) and by the daemon process ([`internal/daemon/manager.go`](https://github.com/kunchenguid/no-mistakes/blob/main/internal/daemon/manager.go)).

### Trusted vs. Untrusted Configuration

`no-mistakes` implements a strict security model that splits configuration into **trusted** and **untrusted** fields:

- **Trusted fields** are read exclusively from the default branch at a pinned SHA to prevent malicious modifications. These include any keys that execute code: `commands.{test,lint,format}`, `agent`, `allow_repo_commands`, and `document.instructions`. The enforcement happens in `loadTrustedRepoConfig` and `assertGateTrustedConfigReadable`.

- **Untrusted fields** can be modified in feature branches and include informational settings like `ignore_patterns`, `auto_fix` policies, and `intent`. These are read from the current checkout via `config.LoadRepoConfig`.

### Core Configuration Sections

A typical configuration file contains several key sections:

- **`commands`**: Defines executable hooks for pipeline steps (trusted).
- **`steps`**: Enables or disables specific gates like `test`, `lint`, or `document`.
- **`auto_fix`**: Configures automatic remediation behavior (untrusted).
- **`document`**: Contains documentation ownership policies (trusted).

## How the Configuration Loading Works

When `no-mistakes run` executes, the system loads configuration in two phases:

1. **Local Configuration**: `config.LoadRepoConfig` reads [`.no-mistakes.yaml`](https://github.com/kunchenguid/no-mistakes/blob/main/.no-mistakes.yaml) from the current working directory to obtain untrusted settings and local overrides.

2. **Trusted Merge**: `loadTrustedRepoConfig` in [`internal/daemon/manager.go`](https://github.com/kunchenguid/no-mistakes/blob/main/internal/daemon/manager.go) fetches the same file from the remote default branch and merges only the trusted fields into the final configuration. If the fetch fails or the trusted config is malformed, the daemon fails closed (`TestLoadTrustedRepoConfig_FailClosedOnFetchFailure`).

The pipeline executor ([`internal/pipeline/executor.go`](https://github.com/kunchenguid/no-mistakes/blob/main/internal/pipeline/executor.go)) then uses this merged configuration to schedule steps and invoke commands.

## Creating Your First Configuration

You can generate a starter configuration using the built-in wizard:

```bash
no-mistakes init

```

This command invokes the wizard defined in [`internal/wizard/wizard.go`](https://github.com/kunchenguid/no-mistakes/blob/main/internal/wizard/wizard.go) to create a [`.no-mistakes.yaml`](https://github.com/kunchenguid/no-mistakes/blob/main/.no-mistakes.yaml) template. Below is a minimal example that demonstrates the separation of trusted and untrusted keys:

```yaml

# .no-mistakes.yaml – repository-specific configuration

# Trusted-only keys (read from default branch)

commands:
  test: go test ./...
  lint: golint ./...
  format: gofmt -w .
document:
  instructions: |
    # Documentation policy

    * One owner per fact
    * Stale docs become pointers
    * No AGENTS.md post-mortems

# Untrusted (can be set by branch)

auto_fix:
  review: 1          # enable auto-fix for review findings

  lint: 0            # keep lint findings manual

steps:
  test:
    enabled: true
  lint:
    enabled: true
  document:
    enabled: true

```

## Common Configuration Scenarios

Customize your pipeline by modifying specific keys in [`.no-mistakes.yaml`](https://github.com/kunchenguid/no-mistakes/blob/main/.no-mistakes.yaml):

**Use a different test command**

Set `commands.test` to override the default test runner. This is a trusted field, so it must exist in the default branch to be accepted.

```yaml
commands:
  test: "gotestsum --format testname"

```

**Skip lint on specific branches**

Disable the lint gate entirely by setting the untrusted `enabled` flag:

```yaml
steps:
  lint:
    enabled: false

```

**Enable auto-fix for review findings**

Control automatic remediation with the untrusted `auto_fix` map (defaults defined in `config.autoFixDefaults`):

```yaml
auto_fix:
  review: 1
  lint: 0

```

**Add a post-push hook**

Define trusted commands that run after successful pushes:

```yaml
commands:
  post_push: "./scripts/check.sh"

```

**Restrict repository-wide commands**

Prevent contributors from enabling arbitrary commands by setting `allow_repo_commands: false` in the trusted default branch configuration.

## Validation and Security

The daemon validates the merged configuration before executing any pipeline steps. If a trusted-only key is missing, malformed, or cannot be fetched from the default branch, the run aborts immediately. This fail-closed behavior ensures that malicious pushes cannot override security-critical settings like command hooks or agent selection.

Key implementation files responsible for validation include:

- [`internal/config/config.go`](https://github.com/kunchenguid/no-mistakes/blob/main/internal/config/config.go) – Defines the `DefaultConfig` struct and parsing logic
- [`internal/daemon/manager.go`](https://github.com/kunchenguid/no-mistakes/blob/main/internal/daemon/manager.go) – Handles trusted config fetching and merging
- [`internal/pipeline/executor.go`](https://github.com/kunchenguid/no-mistakes/blob/main/internal/pipeline/executor.go) – Consumes the final validated configuration

## Summary

- Create a [`.no-mistakes.yaml`](https://github.com/kunchenguid/no-mistakes/blob/main/.no-mistakes.yaml) file at your repository root to configure repository-specific settings for no-mistakes.
- Trusted fields (`commands`, `agent`, `document.instructions`) are read only from the default branch to prevent execution of untrusted code.
- Untrusted fields (`auto_fix`, `steps.enabled`, `ignore_patterns`) can be modified in feature branches.
- Use `no-mistakes init` to generate a starter configuration via the wizard in [`internal/wizard/wizard.go`](https://github.com/kunchenguid/no-mistakes/blob/main/internal/wizard/wizard.go).
- The daemon merges configurations using `config.LoadRepoConfig` and `loadTrustedRepoConfig`, failing closed on any validation errors.
- Refer to [`docs/src/content/docs/reference/repo-config.md`](https://github.com/kunchenguid/no-mistakes/blob/main/docs/src/content/docs/reference/repo-config.md) for complete documentation of available keys.

## Frequently Asked Questions

### Where do I place the no-mistakes configuration file?

Place the [`.no-mistakes.yaml`](https://github.com/kunchenguid/no-mistakes/blob/main/.no-mistakes.yaml) file in the root directory of your Git repository. The CLI and daemon discover this file automatically when running from within the repository, loading it via `config.LoadRepoConfig` while also fetching a trusted version from the default branch to merge security-critical settings.

### What is the difference between trusted and untrusted configuration keys?

Trusted keys control execution and security policies—such as `commands.test`, `agent`, and `allow_repo_commands`—and are read exclusively from the repository's default branch to prevent malicious modifications. Untrusted keys affect only formatting, display, or optional behaviors—like `auto_fix` settings and `ignore_patterns`—and can be safely modified in pull requests without security risks.

### How do I enable auto-fix for specific pipeline steps?

Set the appropriate flag in the `auto_fix` map within your [`.no-mistakes.yaml`](https://github.com/kunchenguid/no-mistakes/blob/main/.no-mistakes.yaml). For example, set `auto_fix.review: 1` to enable automatic fixing of review findings, or `auto_fix.lint: 0` to keep lint findings manual. These settings are defined in the `config.autoFixDefaults` structure and can be overridden per repository since they are considered untrusted configuration.

### Can I override the default test command for my repository?

Yes, override the default test command by setting `commands.test` to your preferred command string in [`.no-mistakes.yaml`](https://github.com/kunchenguid/no-mistakes/blob/main/.no-mistakes.yaml). Because this is a trusted field that executes code, the override will only take effect if it exists in the default branch configuration; the daemon ignores `commands` modifications from feature branches to maintain security boundaries.