gate-pre-git
Local repository governance runtime for GitHub-bound repositories.
gate-pre-git runs at the local Git boundary. Despite the name, it is not a
replacement for Git and does not run before git init; it catches repository
governance failures before they become commits, pushes, pull requests, or
expensive GitHub feedback.
gate-pre-git is for teams that want GitHub to remain the branch-protection and
audit anchor, not the first place where preventable formatting, syntax, secret,
ownership, evidence, and release-governance defects are discovered.
It is not a replacement for pre-commit, Lefthook, Husky, MegaLinter,
Super-Linter, or GitHub Actions. Those tools solve real hook orchestration,
linting, and CI jobs. This project focuses on the missing layer between them:
a vendored Git-boundary contract with governed files, locked local tools,
transactional fixes, manifest identity, doctor drift checks, and cheap
JSON/SARIF audit evidence.
Current Maturity
This repository is a public pre-RC technical foundation published under the MIT
License. It is not a public package release yet. The local baseline is:
- commit
62d3fe3 (chore: establish pre-rc foundation);
- tag
foundation/pre-rc-2026-05-11;
- local
origin/main ref pointing to that baseline for range proof;
- clean worktree after post-baseline evidence.
Public package distribution is intentionally still closed while the support
matrix, package artifacts, and external pinned canaries are finalized.
The public repository also preserves the first GitHub audit failures instead of
rewriting or hiding them. On 2026-05-11, three main workflow runs failed
because the audit workflow wrote its JSON/SARIF artifacts into the same
workspace being audited. The root cause and corrective control are recorded in
docs/incidents/2026-05-11-github-audit-self-contamination.md.
The product contract is not "GitHub can never go red"; it is "preventable
governance failures become executable local rules, and GitHub remains the cheap
final auditor protected by branch rules."
Install From This Checkout
Until a public package channel is opened, use the source checkout as the
installer runtime:
bun install --frozen-lockfile
bun src/cli.ts init --target /path/to/repo --profile auto --yes
/path/to/repo/.gate-pre-git/bin/gate-pre-git doctor --target /path/to/repo
/path/to/repo/.gate-pre-git/bin/gate-pre-git check --target /path/to/repo --all
The intended public CLI remains:
gate-pre-git init --target . --profile auto --yes
gate-pre-git doctor --target .
gate-pre-git check --target . --all
For a Nuxt project:
gate-pre-git init --target . --profile nuxt --yes
gate-pre-git doctor --target .
For documentation-heavy repositories:
gate-pre-git init --target . --profile docs --yes
gate-pre-git doctor --target .
--profile auto detects Nuxt, Node, Python, Go, Rust, docs, shell scripts,
security, and GitHub Actions surfaces before writing .gate-pre-git/config.json.
Default installation writes:
.gate-pre-git/config.json.gate-pre-git/governance.json.gate-pre-git/lock.json.gate-pre-git/bin/gate-pre-git.gate-pre-git/runtime/cli.js.gate-pre-git/cache/.gitignorebiome.json when Biome is enabled, including
json.formatter.expand=auto to align Biome's package.json formatting
with the built-in JSON normalizer- a portable
.gate-pre-git/bin/gate-pre-git launcher that resolves the repo
root before choosing a vendored runtime, source checkout, or PATH runtime
- native Git hooks at the repository's actual
hooks/pre-commit and
hooks/pre-push paths
.github/workflows/gate-pre-git-audit.yml- package scripts when
package.json exists:
gategate:stagedgate:doctorgate:pushgate:auditgate:version-auditgate:release-plan
The native Git hook is the default because it avoids requiring a JavaScript hook
manager in every target repository. Husky is supported with --hook husky, but
it is not required.
The product test suite includes versioned replay workspaces under
fixtures/workspaces/**. These fixtures are materialized into temporary
Git repositories with committed baselines and local origin/main refs, then
mutated and replayed through the push gate. That keeps portability proof tied to
Git behavior instead of inline temporary files.
The migration canary creates a clean external repository, installs the gate,
then uses only the installed launcher to run doctor, check, staged,
push, and audit. It also attempts a real bad commit and expects the native
pre-commit hook to block it.
Trust Model
Local hooks are a powerful default path, not a security boundary. A developer
can bypass hooks with Git options or local configuration. The product responds
by making bypass and drift visible:
