0xDarkMatter/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        │
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:

| Exit code | Meaning | What Claude does | |---|---|---| | 0 | All gates passed; ready for push | Ask user to confirm, then git push <remote> <branch> | | 1 | Secret-scanner hit | Report to user; refuse; suggest git filter-repo / BFG | | 2 | Forbidden file added (.env, key files, .claude/settings.local.json, worktree paths, etc.) | Report; refuse | | 3 | Dirty working tree | Report; ask user to commit or stash first | | 4 | Non-ff divergence | Report; ask user to rebase or merge first | | 5 | Missing dependency (gitleaks) | Report install instructions; refuse | | 6 | No remote specified / unknown remote | Report; ask for clarification |

Dependencies

| Tool | Purpose | Install | |---|---|---| | gitleaks (required) | Secret detection with maintained rule corpus | Windows: scoop install gitleaks or winget install gitleaks.gitleaks / macOS: brew install gitleaks / Linux: apt install gitleaks or binary from https://github.com/gitleaks/gitleaks/releases | | ripgrep (required) | Regex fallback layer + forbidden-file scan | Usually pre-installed; winget install BurntSushi.ripgrep.MSVC / brew install ripgrep | | git ≥ 2.30 | Core operations | Standard |

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.

Trigger phrases

| User intent | Triggers | |---|---| | Direct | "push to origin", "push to github", "push to remote", "git push" | | Question | "can we push?", "safe to push?", "ready to push?" | | Explicit | /push-gate, "run push-gate" |

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

| File | Role | |---|---| | SKILL.md | This file — workflow + rules | | scripts/preflight.sh | Main orchestration (Steps 1–8) | | scripts/scan-secrets.sh | Gitleaks + regex layer (Step 6) | | references/secret-patterns.txt | Regex corpus + false-positive filter words | | assets/ | (empty; reserved for future report templates) |