Push Gate

Push Gate

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.

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. 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  ────────┐
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)

Invocation

# From the repo root (most common)
bash .claude/skills/push-gate/scripts/preflight.sh <remote> <branch>

# When calling from another skill with a different cwd (e.g. github-ops)
bash $HOME/.claude/skills/push-gate/scripts/preflight.sh --cwd <repo-root> <remote> <branch>

--cwd must precede the positional arguments. When omitted, the script operates against $PWD.

The script prints a structured report and exits with:

Dependencies

Both secret layers must pass: gitleaks detects known token formats with a maintained corpus; the regex layer catches generic password = "..." / DSN / connection-string patterns that gitleaks may miss. See references/secret-patterns.txt for the regex corpus. Gitleaks runs with references/gitleaks-config.toml (default rule set + an allowlist for public-by-design tokens, e.g. Mapbox pk.*); if that file is absent, the scan falls back to gitleaks' built-in default config.

Trigger phrases

Claude should invoke scripts/preflight.sh on any of these. Do not invoke on local pushes (git push <path> or git push .) — those are the updateInstead pattern for cross-worktree landings and don't leave the host.

False-positive handling

The regex layer filters common false positives automatically (env-var references, shell fallbacks, placeholders with ...). Gitleaks has its own .gitleaksignore file mechanism — add entries there for confirmed-safe findings, committed at repo root. The skill will not offer an inline bypass.

Not in scope

• Release automation (changelog, tagging, version bumps) — that's ci-cd-ops / git-ops territory.
• Full security audit — that's security-ops (broader SAST + dep scanning).
• Force-push / history rewriting — intentionally excluded; requires explicit out-of-band authorization.
• Signed-commit verification — add later if needed.

Files