GForge

Governance Forge — an engineering governance platform that helps teams forge consistent development standards through Git automation, quality gates, and developer tooling.

GForge brings engineering standards to the one place every change passes through: the commit. Its first governance capability is a secret firewall — a managed global Git hook that stops credentials from ever entering your history, on every repository, across your whole team.

Why GForge

A single leaked API key, database password, or private key in a commit can mean a production incident, a costly rotation, and a permanent entry in Git history. Per-project hooks drift, get skipped, or are never installed. GForge makes the guardrail global, automatic, and uniform for every developer and every repo — so the standard is enforced by default, not by discipline.

Features

• Install once, protected everywhere. Configures Git's global core.hooksPath, so the firewall applies to every repository on the machine.
• Deep, layered detection
  • .env cross-reference — blocks any staged file that hardcodes a real value from your git-ignored .env files (the classic "pasted a token out of .env").
  • Provider rules — 25+ credential shapes: AWS, GitHub/GitLab, Google, Slack, Stripe, Twilio, SendGrid, npm, PyPI, OpenAI/Anthropic, PEM private keys, JWTs, database URLs, and more.
  • Generic secrets — any credential keyword assigned to a hardcoded value (DB_PASSWORD=…, password: "…", api_key = "…").
  • Entropy — high-entropy strings that carry no recognizable name.
• Low noise by design. References like process.env.DB_PASSWORD, placeholders, and env templates (.env.example) are not flagged, so correct code keeps flowing.
• Never leaks the secret. Reports only file paths, line numbers, and rule names — the matched value is never printed.
• Encoding-aware. Handles UTF‑8, UTF‑16, and BOM-prefixed files (e.g. those written by PowerShell) so nothing slips through as "binary".
• Zero-config upkeep. Self-installing on npm i -g, self-upgrading, and auto-updating — every workstation stays current on its own.
• gitleaks turbo (optional). If gitleaks is on PATH, GForge runs it too and merges the findings.
• Cross-platform, zero runtime dependencies.

Requirements

• Node.js 20 or newer
• Git

Installation

npm install -g gforge

That's the whole setup — installing globally configures the hooks for every repository automatically. From the next commit onward, changes are scanned for secrets. Confirm anytime with:

gforge verify

Quick start

# See the current status of your workstation
gforge verify

# Try it — a hardcoded secret is blocked before it can be committed
echo 'DB_PASSWORD=S3cr3t-Value-123' > config.txt
git add config.txt
git commit -m "add config"
# → GForge blocks the commit and names config.txt (the value is never printed)

Commands

gforge <command> [--force]

| Command | Description | | --- | --- | | gforge install | Upgrade to the latest version (if any) and install the global hooks. | | gforge verify | Read-only health check of the environment and installed hooks. | | gforge update | Upgrade to the latest version (if any) and refresh the hooks. | | gforge uninstall | Remove GForge-owned hooks and restore your previous Git config. | | gforge version | Print the installed version. | | gforge help | Print usage. |

--force (with install/update) reinstalls the latest release even if you are already on it. GForge never downgrades below your installed version.

How detection works

The pre-commit hook scans only the files staged for the current commit — not the whole repository — and blocks the commit if any appear to contain a secret. It reports file paths, line numbers, and rule names, and never prints the matched value. Detection runs several layers in order:

1. .env cross-reference — the highest-precision signal: values read (in memory only) from your git-ignored .env files, matched verbatim in staged code.
2. Provider rules — fixed credential shapes for the major cloud and SaaS providers.
3. Generic secrets — credential keywords assigned to a hardcoded value; smart enough to ignore process.env.*, function calls, ${VAR} interpolation, and obvious placeholders.
4. Entropy — unnamed high-entropy strings, tuned to skip Git SHAs, UUIDs, and lockfiles.
5. Secret files — .env (and .env.* except templates), id_rsa, *.p12/*.pfx, keystores, .git-credentials, .netrc, and more.

Detection is best-effort and complements — not replaces — good secret hygiene.

Managing false positives

Maximum coverage occasionally flags something safe. Three escape hatches:

• Inline: add a gforge:allow (or gitleaks:allow) comment on the line.

• Per-repo: add a path or pattern to a .gforgeignore file at the repo root (a .gitleaksignore is also honored):

  # .gforgeignore
  test/fixtures/
  ^docs/sample-config\.md$

• One-off: bypass a single commit with git commit --no-verify.

Staying up to date

gforge update upgrades the package to the latest published release and refreshes the hook — no manual npm install needed. GForge also keeps itself current on its own: at most once a day it checks for a new version in a detached background process (it never delays or blocks a commit), installs it, and prints a one-line notice on commit:

gforge: v1.2.0 is available (you have v1.1.0). Run: gforge update

Configuration

Behavior is controlled entirely through environment variables — there is no config file to manage.

| Variable | Effect | | --- | --- | | GFORGE_AUTO_UPDATE=0 | Notify only; do not auto-install new versions (default: auto-install on). | | GFORGE_NO_SELF_UPDATE=1 | Skip the npm self-upgrade in install/update (CI / air-gapped). | | GFORGE_SKIP_POSTINSTALL=1 | Skip automatic hook setup during npm install. | | GFORGE_NODE=/path/to/node | Pin the Node.js runtime the hook uses. |

If a repository or the system already defines its own core.hooksPath (e.g. Husky or lefthook), GForge does not override it; run gforge install to have GForge take over. Automatic setup is skipped in CI (CI environment variable).

Cross-platform support

| Platform | Shells | | --- | --- | | macOS | Bash, Zsh | | Linux | Bash | | Windows | Git Bash, WSL, PowerShell (via Git for Windows) |

The scanner runs on Node.js; the hook is a small POSIX shell shim that locates Node robustly (including on Git for Windows) and fails closed if it cannot — a commit is never allowed through unscanned.

What GForge changes on your machine

GForge is transparent and fully reversible. It touches only your global Git config and a single directory in your home folder:

• ~/.gforge/hooks/ — the managed hook and scanner (core.hooksPath points here).
• ~/.gforge/state.json — records your previous core.hooksPath so uninstall can restore it.

gforge uninstall removes GForge-owned files and restores your prior configuration.

Programmatic use

GForge is primarily a CLI, but the command runner is exposed for scripting:

import { runCli } from "gforge";

const result = await runCli(["verify"], { stdout: process.stdout, stderr: process.stderr });
process.exit(result.exitCode);

Roadmap

The secret firewall is the first governance capability. Planned directions for the platform include:

• Additional commit-time quality gates (commit message and branch conventions, large-file and merge-conflict guards).
• Shareable, versioned org policy packs.
• Reporting and audit for governance coverage across a team.

Contributing

Issues and pull requests are welcome at the GitHub repository. Please run npm test before submitting, keep changes focused, and preserve the Apache-2.0 license header and NOTICE.

npm test               # run the test suite
npm run package:check  # inspect the publishable package contents

Security

To report a vulnerability, follow the process in SECURITY.md. Do not open a public issue for security reports, and never include real secrets in a report.

License

Licensed under the Apache License 2.0. Please preserve the NOTICE file when redistributing.