# How no-mistakes Loads Trusted Config from a Pinned SHA on the Default Branch

> Learn how no-mistakes ensures trusted config loading from a pinned SHA on the default branch by resolving to an immutable SHA at runtime for immutable pipeline integrity.

- Repository: [Kun Chen/no-mistakes](https://github.com/kunchenguid/no-mistakes)
- Tags: deep-dive
- Published: 2026-07-25

---

**no-mistakes guarantees pipeline integrity by resolving the default branch to an immutable SHA at runtime and reading [`.no-mistakes.yaml`](https://github.com/kunchenguid/no-mistakes/blob/main/.no-mistakes.yaml) directly from that git tree, aborting the run if the trusted configuration is missing or invalid.**

The `no-mistakes` engine treats repository configuration as a security boundary. To prevent malicious contributors from altering critical settings mid-pipeline, the daemon loads the **trusted config** exclusively from a **pinned SHA** on the default branch. This design ensures that only the repository state explicitly marked as trusted—typically the merge target—can influence security-sensitive behavior.

## Resolving the Default Branch Tip

Before any agent executes, the daemon establishes a ground-truth commit. In [`internal/git/git.go`](https://github.com/kunchenguid/no-mistakes/blob/main/internal/git/git.go), the function **`resolveUpstreamURL`** fetches `origin/<default>` and extracts the SHA of the default branch’s tip. This value is stored as **`trustedSHA`** in the run record and remains immutable for the pipeline’s duration.

## Loading the Configuration from the Pinned Tree

With the `trustedSHA` in hand, the daemon calls **`loadTrustedRepoConfig`** in [`internal/daemon/manager.go`](https://github.com/kunchenguid/no-mistakes/blob/main/internal/daemon/manager.go). This function performs a **git-object-only read**: it invokes `git.ShowFile` (via `git.RunBare`) to extract the raw bytes of [`.no-mistakes.yaml`](https://github.com/kunchenguid/no-mistakes/blob/main/.no-mistakes.yaml) from the tree associated with the pinned SHA. Crucially, this operation **never checks out files** to the working directory, ensuring the current (potentially untrusted) HEAD cannot influence the result.

```go
// internal/daemon/manager.go
func loadTrustedRepoConfig(ctx context.Context, dir, sha, runID string) *config.RepoConfig {
    // Read .no-mistakes.yaml directly from the git tree at the pinned SHA
    out, err := git.RunBare(ctx, dir, "show", sha+":.no-mistakes.yaml")
    if err != nil {
        return nil // Fail closed: unreadable tree
    }
    cfg, err := config.LoadRepoConfig(out)
    if err != nil {
        return nil // Fail closed: invalid YAML
    }
    return cfg
}

```

## Parsing and Validating the Trusted Config

The raw YAML bytes are passed to **`config.LoadRepoConfig`** in [`internal/config/config.go`](https://github.com/kunchenguid/no-mistakes/blob/main/internal/config/config.go). This unmarshals the content into a strongly-typed **`config.RepoConfig`** struct. Fields marked as **trusted-only**—such as `allow_repo_commands` and `document.instructions`—are sourced exclusively from this object. All other configuration values may be read from the pushed branch, but security-critical directives are bound to the immutable default-branch snapshot.

## Fail-Closed Abort on Integrity Failure

The loading mechanism is designed to **fail closed**. If `resolveUpstreamURL` cannot fetch the remote, if [`.no-mistakes.yaml`](https://github.com/kunchenguid/no-mistakes/blob/main/.no-mistakes.yaml) is missing from the pinned tree, or if `LoadRepoConfig` encounters a parse error, **`loadTrustedRepoConfig`** returns `nil`. The caller, **`run.StartRun`** (also in [`internal/daemon/manager.go`](https://github.com/kunchenguid/no-mistakes/blob/main/internal/daemon/manager.go)), treats a `nil` trusted configuration as a fatal error and halts the pipeline before any agents are spawned. This prevents the system from falling back to a potentially compromised working-copy configuration.

## Security Guarantees and Test Coverage

Because the SHA is resolved once at the start of the run, any subsequent changes to the default branch are invisible to the current execution. The daemon never reads [`.no-mistakes.yaml`](https://github.com/kunchenguid/no-mistakes/blob/main/.no-mistakes.yaml) from the local filesystem; it always reads from the git object database. This behavior is enforced by unit tests such as **`TestLoadTrustedRepoConfig_FailClosedOnFetchFailure`** and **`TestLoadTrustedRepoConfig_PinnedSHAReadsFreshDefaultBranch`** located in [`internal/config/config_repo_trust_test.go`](https://github.com/kunchenguid/no-mistakes/blob/main/internal/config/config_repo_trust_test.go). The authoritative list of trusted-only keys is documented in [`docs/src/content/docs/reference/repo-config.md`](https://github.com/kunchenguid/no-mistakes/blob/main/docs/src/content/docs/reference/repo-config.md).

## Summary

- **SHA Resolution**: `resolveUpstreamURL` in [`internal/git/git.go`](https://github.com/kunchenguid/no-mistakes/blob/main/internal/git/git.go) locks the default branch to a specific commit at runtime.
- **Object-Only Reads**: `loadTrustedRepoConfig` in [`internal/daemon/manager.go`](https://github.com/kunchenguid/no-mistakes/blob/main/internal/daemon/manager.go) reads [`.no-mistakes.yaml`](https://github.com/kunchenguid/no-mistakes/blob/main/.no-mistakes.yaml) via `git.RunBare` without touching the working directory.
- **Strict Parsing**: `config.LoadRepoConfig` in [`internal/config/config.go`](https://github.com/kunchenguid/no-mistakes/blob/main/internal/config/config.go) unmarshals trusted-only fields into a strongly-typed struct.
- **Fail-Closed**: Any resolution or parsing error causes `loadTrustedRepoConfig` to return `nil`, forcing `run.StartRun` to abort immediately.
- **Immutability**: The pinned SHA guarantees that later pushes to the default branch cannot alter the configuration of an in-flight pipeline.

## Frequently Asked Questions

### What happens if the default branch moves forward after the run starts?

The daemon resolves the SHA once during initialization and stores it in the run record. Subsequent updates to the default branch do not affect the pinned SHA, ensuring the configuration remains immutable for the duration of the pipeline.

### Can an attacker modify the trusted config by committing to a feature branch?

No. The daemon explicitly reads [`.no-mistakes.yaml`](https://github.com/kunchenguid/no-mistakes/blob/main/.no-mistakes.yaml) from the tree of the pinned SHA on the default branch using `git show`. It never reads the file from the checked-out working copy or from a non-default branch, so feature branch changes cannot influence the trusted configuration.

### Which configuration fields are considered "trusted-only"?

Fields that control security-sensitive behavior—such as `allow_repo_commands`, `document.instructions`, and `commands.*` definitions—are designated trusted-only. These values are sourced exclusively from the `config.RepoConfig` loaded from the default-branch SHA. The full list is documented in [`docs/src/content/docs/reference/repo-config.md`](https://github.com/kunchenguid/no-mistakes/blob/main/docs/src/content/docs/reference/repo-config.md).

### How does the system handle a missing or malformed [`.no-mistakes.yaml`](https://github.com/kunchenguid/no-mistakes/blob/main/.no-mistakes.yaml) on the default branch?

The function `loadTrustedRepoConfig` returns `nil` if the file is absent, unreadable, or fails YAML parsing. The caller `run.StartRun` treats this as a fatal error and terminates the run before executing any steps, preventing operation with an undefined security policy.