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

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, 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 – Contains resolveForcePushDecision, the core lease-guarded logic that evaluates push safety.
• 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 – Calls resolveForcePushDecision before executing any push operation.
• 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 demonstrates how the safety check integrates into the push workflow:

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, 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 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 within the resolveForcePushDecision function. This function is invoked by internal/pipeline/steps/push.go before executing pushes and by 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.

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