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
- Gitleaks is a required dependency. If not installed, emit the install instructions and refuse. Do not silently fall back to regex-only.
- Any secret-scanner hit ⇒ refuse. No bypass flag. Confirmed-safe findings go into the committed repo-local allowlists (
.gitleaksignorefor gitleaks,.pushgate-allowfor the regex layer — see §False-positive handling), never an inline override. Real secrets force the user to rewrite history and re-invoke the gate. - Never
--forcepush. The gate never passes a force flag. If the user needs to force-push, that's a separate conversation with explicit authorization. - Never
--no-verify. Don't skip hooks. - Working tree must be clean. Refuse on dirty tree (uncommitted work could be accidentally stashed into the push flow).
- Remote must be named. Refuse if
git pushis 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 .pushgate-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)
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. 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
| 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
Both secret layers have a repo-local, committed allowlist. The gate still refuses any hit not explicitly allowed, and the skill will not offer an inline bypass — a confirmed-safe finding earns a reviewed entry in the repo, not a one-off override.
| Layer | Allowlist file (repo root) | Entry format |
|---|---|---|
| gitleaks | .gitleaksignore |
gitleaks fingerprint (commit:file:rule:line) |
| regex | .pushgate-allow |
<repo-relative-path>:<line-regex> |
The regex layer also drops common false positives automatically (env-var references, shell fallbacks, placeholders with ...) before the allowlist is consulted.
.pushgate-allow rules:
- One entry per line;
#comments allowed. Each entry must carry a reason comment directly above it — the scanner warns when one is missing. - Entries split on the first
:— a repo-relative path (forward slashes, no:in the path), then a Rust-regex matched against the added line's full content. No line numbers anywhere: they drift on every edit above them; a content anchor does not. - An entry suppresses hits only in that exact file. Every other hit still refuses.
- On refusal, the scanner prints a ready-made anchored entry per hit — copy it under a reason comment, commit, and re-run the gate.
- Entries whose file is gone, or whose regex no longer matches any line of that file at the branch tip, are reported as stale (warning, non-gating) — prune them.
- The gate's clean-tree rule (hard rule 5) means the file is always committed by the time it is consulted — an uncommitted allowlist edit fails Step 3 before it can suppress anything.
Example:
# reason: test fixture — wire-snapshot key exercised by MCP wire tests, not a credential
packages/mcp/test/client.test.ts:^ apiKey: "wire-snapshot-key",$
Not in scope
- Release automation (changelog, tagging, version bumps) — that's
ci-cd-ops/git-opsterritory. - 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 |
references/gitleaks-config.toml |
Gitleaks config: default rules + public-token allowlist (used by scan-secrets.sh when present) |
tests/run.sh |
Offline behavioural self-test for the secret scanner (planted secrets, FP filter, allowlist, stale entries) |
assets/ |
(empty; reserved for future report templates) |
Per-repo (not shipped with the skill): .gitleaksignore and .pushgate-allow, committed at the scanned repo's root — see §False-positive handling.