push-preflight

Push Preflight

Formalised pre-push safety check. Runs before every git push <remote> where the remote is not a local file path. Refuses on secret hits; warns on size/forbidden-file; confirms intent before pushing.

Use this skill whenever the user asks to push, or before Claude runs git push to any remote. Complements git-ops (which handles the push itself) — this is the gate that runs immediately before.

Why the name. Formerly push-gate. It runs six checks (secret scan, clean tree, forbidden files, fast-forward, size advisory, open-issue advisory), so secret-scan would undersell it, and mislead: it scans only the commits being pushed, never history (that is security-ops). The name matches scripts/preflight.sh. The secret scan leads the description because the description, not the name, is what selects the skill.

Hard rules

1. Gitleaks is a required dependency. If not installed, emit the install instructions and refuse. Do not silently fall back to regex-only.
2. Any secret-scanner hit ⇒ refuse. No bypass flag. Confirmed-safe findings go into the committed repo-local allowlists (.gitleaksignore for gitleaks, .push-preflight-allow for the regex layer — see §False-positive handling), never an inline override. Real secrets force the user to rewrite history and re-invoke the gate.
3. Never --force push. The gate never passes a force flag. If the user needs to force-push, that's a separate conversation with explicit authorization.
4. Never --no-verify. Don't skip hooks.
5. Working tree must be clean. Refuse on dirty tree (uncommitted work could be accidentally stashed into the push flow).
6. Remote must be named. Refuse if git push is called without an explicit remote and branch.

Workflow

Step 1  →  Identify remote + branch
Step 2  →  git fetch <remote>
Step 3  →  Verify working tree clean
Step 4  →  Compute pending commits (count + list)
Step 5  →  Check divergence (non-ff ⇒ require user to rebase first)
Step 6  →  Secret scan  ────────┐  gitleaks honours .gitleaksignore,
                                │  regex layer honours .push-preflight-allow
Step 7  →  Forbidden-file scan  │ refuse on any hit
Step 8  →  Size advisory        │
        →  Open-issue advisory (github-ops; informational, never gates)
Step 9  →  Explicit confirm     │
Step 10 →  git push <remote> <branch>
Step 11 →  Post-push verify (ls-remote matches pushed SHA)