# How `resolveForcePushDecision` and `lastSeenSHA` Prevent Accidental Force-Pushes in no-mistakes

> Learn how no-mistakes prevents accidental force-pushes. Discover how resolveForcePushDecision and lastSeenSHA compare remote HEAD against stored SHAs for secure Git workflows.

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

---

**The `no-mistakes` pipeline prevents accidental force-pushes by using `resolveForcePushDecision` to compare the current remote HEAD against a stored `lastSeenSHA`, rejecting any push where the remote has advanced since the pipeline last checked.**

The `no-mistakes` repository implements a fail-closed safety mechanism to protect shared Git history from destructive overwrites. By anchoring force-push decisions to a previously observed remote state stored in `lastSeenSHA`, the system ensures developers cannot accidentally overwrite commits pushed by others. This protection 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 verification system.

## The `resolveForcePushDecision` Safety Check

The ** `resolveForcePushDecision`** function serves as the gatekeeper for all force-push operations in the pipeline. Before allowing any destructive rewrite of remote history, it performs a fresh `git ls-remote` call to obtain the actual current tip of the target branch. This real-time verification ensures the pipeline's view of the remote has not become stale since the last check.

The function accepts several key parameters: `gitRun` (the command executor), `pushURL`, `ref` (the branch reference), `newHeadSHA` (the local commit being pushed), `lastSeenSHA` (the previously observed remote state), and `baseSHA` (the PR base commit for additional safety checks).

```go
// Example: deciding whether a force‑push is allowed
decision, err := resolveForcePushDecision(
    gitRun,            // wrapper around exec.Command
    pushURL,           // remote URL for the push
    ref,               // e.g. "refs/heads/feature"
    newHeadSHA,        // the SHA we want to push
    lastSeenSHA,       // remote head the pipeline last saw
    baseSHA,           // base commit of the PR (used for extra safety)
)
if err != nil {
    // handle error – push will be aborted
}
if decision == forcePushAllowed {
    // safe to push (or force‑push with lease)
}

```

## How `lastSeenSHA` Acts as a Push Lease

**`lastSeenSHA`** is not the SHA of the latest local commit; it is a snapshot of the remote tip taken earlier in the pipeline execution and stored in `runs.last_seen_sha`. This value represents the pipeline's last known good state of the remote branch.

By anchoring the push decision to this stored value, the system implements a **compare-and-swap** style lease. The pipeline refuses to force-push unless it can prove the remote has not moved since it was last examined. This prevents the classic "force-push over someone else's work" scenario where a stale view of the remote would otherwise allow destructive rewrites.

## Three Conditions That Permit Force-Pushing

The function allows force-pushes only under three specific safe conditions:

1. **New branch creation** – The ref does not exist remotely, so a force-push is harmless.
2. **Unchanged remote** – The `current` remote HEAD equals `lastSeenSHA`, proving no one has pushed since the pipeline last checked.
3. **Already up-to-date** – The `newHeadSHA` already matches the current remote HEAD, meaning no rewrite is actually needed.

If any of these conditions are met, the function returns `forcePushAllowed`. Otherwise, it returns `forcePushRejected` with an error explaining that the remote head has changed.

```go
// Inside `resolveForcePushDecision` (simplified)
current, err := gitRun.Run("ls-remote", pushURL, ref)
if lastSeenSHA != "" && current == lastSeenSHA {
    // Remote unchanged – safe to force‑push
    return forcePushAllowed, nil
}
if current == newHeadSHA {
    // Already up‑to‑date – no force‑push needed
    return forcePushAllowed, nil
}
return forcePushRejected, fmt.Errorf("remote head advanced from %s to %s", lastSeenSHA, current)

```

## Pipeline Integration and Fail-Closed Behavior

The safety mechanism extends across multiple pipeline steps to ensure consistent protection:

- **CI Fix Step** ([`internal/pipeline/steps/ci_fix.go`](https://github.com/kunchenguid/no-mistakes/blob/main/internal/pipeline/steps/ci_fix.go)): Also calls `resolveForcePushDecision` when pushing automated fixes, ensuring the same safety checks apply after an automated commit.
- **Push Step** ([`internal/pipeline/steps/push.go`](https://github.com/kunchenguid/no-mistakes/blob/main/internal/pipeline/steps/push.go)): Uses the decision outcome to choose between a normal push, a safe force-push with lease anchored to `lastSeenSHA`, or an abort with a clearly reported finding.

Together, these checks enforce a **fail-closed** policy: any ambiguous or out-of-date remote state results in a rejected push rather than a silent overwrite. The unit tests in [`internal/pipeline/steps/forcepush_decision_test.go`](https://github.com/kunchenguid/no-mistakes/blob/main/internal/pipeline/steps/forcepush_decision_test.go) verify both allowed and rejected cases to maintain this safety invariant.

## Summary

- **`resolveForcePushDecision`** in [`internal/pipeline/steps/forcepush.go`](https://github.com/kunchenguid/no-mistakes/blob/main/internal/pipeline/steps/forcepush.go) acts as the central gatekeeper for force-push safety.
- **`lastSeenSHA`** stores the pipeline's last observed remote state, functioning as a lease token that must match the current remote HEAD.
- The system allows force-pushes only for new branches, unchanged remotes, or already-up-to-date states.
- Both the CI fix step and push step reuse this logic, ensuring consistent protection across all push operations.
- When the remote has advanced beyond `lastSeenSHA`, the function returns `forcePushRejected` to prevent overwriting others' work.

## Frequently Asked Questions

### What exactly is `lastSeenSHA` in the no-mistakes pipeline?

`lastSeenSHA` is the commit hash of the remote branch tip as observed earlier in the pipeline execution, stored in the database field `runs.last_seen_sha`. It is not the local commit SHA, but rather a snapshot of the remote state used to detect if someone else has pushed to the branch since the pipeline began.

### How does `resolveForcePushDecision` detect out-of-band pushes?

The function runs `git ls-remote` to fetch the current remote HEAD and compares it against the stored `lastSeenSHA`. If these values differ, it indicates the remote has advanced out-of-band (for example, by another developer pushing directly), and the function rejects the force-push to prevent overwriting those new commits.

### What happens when `resolveForcePushDecision` rejects a push?

When the remote HEAD has advanced beyond `lastSeenSHA`, the function returns `forcePushRejected` along with an error message indicating the remote head has changed. The calling code in [`push.go`](https://github.com/kunchenguid/no-mistakes/blob/main/push.go) or [`ci_fix.go`](https://github.com/kunchenguid/no-mistakes/blob/main/ci_fix.go) then aborts the operation and reports the conflict, forcing the developer to pull the latest changes and reconcile before retrying.

### Is this mechanism only used for force-pushes or all pushes?

While specifically designed to prevent dangerous force-pushes, the decision logic is evaluated for push operations that might require rewriting history. Normal fast-forward pushes that don't require force flags may proceed through different pathways, but any operation that could overwrite remote history must pass the `resolveForcePushDecision` check first.