# Force Push Safety Mechanisms in no-mistakes: Lease-Guarded Protection Against Data Loss

> Discover no-mistakes lease-guarded force push protection. Abort history rewrites and prevent data loss with built-in safety mechanisms against remote divergence and discarded commits.

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

---

**The no-mistakes repository implements lease-guarded force push protection that aborts history rewrites if the remote has diverged since the run observed it, or if any discarded commits are not already present by patch-ID.**

The `kunchenguid/no-mistakes` tool protects against accidental data loss during automated Git operations by enforcing strict validation before rewriting branch history. These force push safety mechanisms ensure that pipeline steps never overwrite unseen upstream work while still permitting legitimate history rewrites during automated fixes. Understanding these guardrails is essential for safely deploying automated CI/CD pipelines that modify Git history.

## How Force Push Safety Works in no-mistakes

The safety logic centers on the `resolveForcePushDecision` function in [`internal/pipeline/steps/forcepush.go`](https://github.com/kunchenguid/no-mistakes/blob/main/internal/pipeline/steps/forcepush.go), which implements a lease-based validation system. This function compares the current remote state against the state observed at the start of the run before authorizing any force push operation.

### Remote-Head Re-Read Validation

Before deciding whether to force push, the mechanism re-fetches the current ref from the push remote to obtain the latest state. This prevents the pipeline from acting on stale information if an out-of-band commit occurred after the initial fetch. The function validates that the remote head matches the `lastSeenSHA` recorded when the run first observed the branch, ensuring the decision uses current data.

### Lease-Guarded Decision Logic

The core safety check permits a force push only if one of four conditions is met:

1. **The branch is new** – no remote ref exists yet.
2. **The remote already equals the new head** – the desired state is already present.
3. **The remote equals the last-seen SHA** – the remote has not advanced since the run started.
4. **All lost commits are present by patch-ID** – any commits that would be discarded are already incorporated on the remote (excluding the run's base commit).

If none of these conditions satisfy the validation, the function returns an error and the push aborts, protecting contributor work from accidental overwrites.

### Patch-ID Exclusion for Base Commits

The mechanism ignores commits anchored by `baseSHA` (the run's base commit) when checking for lost commits. This allows the pipeline to rewrite its own base commit without triggering a safety violation, while still protecting external commits that have been added since the run began. The patch-ID comparison ensures semantic equivalence even if commit hashes differ.

### Fast-Path Optimization

For performance, `resolveForcePushDecision` includes shortcuts that return `forcePushAllowed` immediately when:

- The `newHeadSHA` equals the `lastSeenSHA` (nothing changed)
- The remote already matches the new head (idempotent operation)

These fast paths avoid expensive diff calculations when no actual rewrite is necessary.

## Core Implementation Files

The force push safety system spans several files in the `internal/pipeline/steps` directory:

- **[`internal/pipeline/steps/forcepush.go`](https://github.com/kunchenguid/no-mistakes/blob/main/internal/pipeline/steps/forcepush.go)** – Contains `resolveForcePushDecision`, the core lease-guarded logic that evaluates push safety.
- **[`internal/pipeline/steps/forcepush_decision_test.go`](https://github.com/kunchenguid/no-mistakes/blob/main/internal/pipeline/steps/forcepush_decision_test.go)** – Comprehensive unit tests covering edge cases including missing refs, out-of-band commits, and missing last-seen SHAs.
- **[`internal/pipeline/steps/push.go`](https://github.com/kunchenguid/no-mistakes/blob/main/internal/pipeline/steps/push.go)** – Calls `resolveForcePushDecision` before executing any push operation.
- **[`internal/pipeline/steps/ci_fix.go`](https://github.com/kunchenguid/no-mistakes/blob/main/internal/pipeline/steps/ci_fix.go)** – Reuses the decision logic when auto-fixing failing checks requires history rewrites.

## Practical Implementation Example

The following pattern from [`internal/pipeline/steps/push.go`](https://github.com/kunchenguid/no-mistakes/blob/main/internal/pipeline/steps/push.go) demonstrates how the safety check integrates into the push workflow:

```go
decision, err := resolveForcePushDecision(
    gitRun,               // runner that executes git commands
    pushURL,              // remote URL
    ref,                  // ref e.g., "refs/heads/feature"
    headBeingPushed,      // SHA intended for push
    lastSeen,             // SHA observed at run start
    sctx.Run.BaseSHA,     // base commit anchoring the run
)
if err != nil {
    return fmt.Errorf("force-push decision failed: %w", err)
}
if decision != forcePushAllowed {
    return fmt.Errorf("refusing unsafe force-push: %s", decision)
}
// Safe to proceed with force push

```

If an out-of-band commit is detected and the missing commits are not present by patch-ID, the function returns an error status and the operation terminates before contacting the remote.

## Testing Coverage

The safety mechanisms include extensive validation in [`forcepush_decision_test.go`](https://github.com/kunchenguid/no-mistakes/blob/main/forcepush_decision_test.go), which verifies behavior across scenarios including missing references, unchanged heads, concurrent modifications, and missing last-seen SHA records. These tests ensure the guardrails remain reliable as the codebase evolves.

## Summary

- **Lease-based validation** records the remote SHA at run start and only permits rewrites if the remote remains unchanged or lost commits are accounted for.
- **Remote-head re-read** prevents decisions based on stale data by fetching the current ref immediately before evaluation.
- **Patch-ID matching** allows the system to recognize semantically equivalent commits even with different hashes, preventing false positives on rebased commits.
- **Fast-path optimizations** skip expensive checks when no actual history change is required.
- **Comprehensive test coverage** in [`forcepush_decision_test.go`](https://github.com/kunchenguid/no-mistakes/blob/main/forcepush_decision_test.go) validates edge cases and maintains safety guarantees.

## Frequently Asked Questions

### What prevents no-mistakes from overwriting commits pushed during pipeline execution?

The **remote-head re-read** mechanism fetches the current ref immediately before the push decision, comparing it against the `lastSeenSHA` recorded when the run started. If the remote has diverged and the new commits are not present by patch-ID, `resolveForcePushDecision` returns an error and aborts the push.

### How does no-mistakes handle rewriting its own base commits?

The **patch-ID exclusion** logic ignores commits anchored by `baseSHA` when checking for lost work. This allows the pipeline to rewrite commits that originated from the run itself while still protecting external commits that appeared after the run began.

### Where is the force push safety logic implemented in the codebase?

The primary implementation resides in [`internal/pipeline/steps/forcepush.go`](https://github.com/kunchenguid/no-mistakes/blob/main/internal/pipeline/steps/forcepush.go) within the `resolveForcePushDecision` function. This function is invoked by [`internal/pipeline/steps/push.go`](https://github.com/kunchenguid/no-mistakes/blob/main/internal/pipeline/steps/push.go) before executing pushes and by [`internal/pipeline/steps/ci_fix.go`](https://github.com/kunchenguid/no-mistakes/blob/main/internal/pipeline/steps/ci_fix.go) when automated fixes require history rewrites.

### What happens if the remote branch state matches the intended push state?

The **fast-path optimization** in `resolveForcePushDecision` detects when `newHeadSHA` equals `lastSeenSHA` or when the remote already matches the new head, returning `forcePushAllowed` immediately without performing expensive diff calculations or patch-ID comparisons.