How to Configure Repository-Specific Settings for no-mistakes

To configure repository-specific settings for no-mistakes, create a .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 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 Configuration File

The repository-specific configuration lives in .no-mistakes.yaml at the repository root. This file is read by both the CLI when starting a run (internal/cli/daemon_cmd.go) and by the daemon process (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 from the current working directory to obtain untrusted settings and local overrides.

2. Trusted Merge: loadTrustedRepoConfig in 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) 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:

no-mistakes init

This command invokes the wizard defined in internal/wizard/wizard.go to create a .no-mistakes.yaml template. Below is a minimal example that demonstrates the separation of trusted and untrusted keys:

# .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:

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.

commands:
  test: "gotestsum --format testname"

Skip lint on specific branches

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

steps:
  lint:
    enabled: false

Enable auto-fix for review findings

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

auto_fix:
  review: 1
  lint: 0

Add a post-push hook

Define trusted commands that run after successful pushes:

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 – Defines the DefaultConfig struct and parsing logic
• internal/daemon/manager.go – Handles trusted config fetching and merging
• internal/pipeline/executor.go – Consumes the final validated configuration

Summary

• Create a .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.
• 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 for complete documentation of available keys.

Frequently Asked Questions

Where do I place the no-mistakes configuration file?

Place the .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. 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. 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}