A policy-enforcing git push proxy for enterprises. fogwall sits between the developer's git push and the upstream host
(GitHub, GitLab, Bitbucket, Forgejo), enforcing commit policies, scanning for secrets, verifying identities, and gating
pushes behind a review workflow — with real-time feedback directly in the developer's terminal.
Built on JGit for native git protocol handling, Jetty for the HTTP layer, and Spring, React & Tailwind for the dashboard.
Both proxy modes enforce the same set of configurable validation rules:
- 🔒 Repository URL allow/deny rules (literal, glob, and regex)
- ✉️ Author email domain allow/block list
- 📝 Commit message validation (literal + regex)
- 🔍 Diff generation and content scanning
- 🔑 Secret scanning (gitleaks)
- 🪪 SCM identity verification (resolve token → SCM user)
- 🛡️ User push permissions (per-repo RBAC)
- 🕵️ Git history integrity (prevent hidden commits and empty branch pushes)
- ✍️ GPG/SSH commit signature verification
- ✅ Approval gate with configurable mode (auto-approve or manual review via dashboard)
- 📋 Aggregate failure reporting (all errors surfaced at once)
- 📡 Real-time terminal feedback during
git pushas validation runs (store-and-forward) - 📊 Fetch auditing
The web dashboard provides push management, approval workflows, and operational tooling:
- 📜 Push lifecycle timeline (received → validated → approved → forwarded)
- ✅ Attestation questionnaire with approve/reject/cancel and audit trail
- 🔓 Self-certify grant for trusted contributors (IdP group-backed)
- 🛡️ Admin override with explicit opt-in and separate audit logging
- 🔒 Allow/deny access rules (literal, glob, regex) scoped by provider and operation
- 👤 Per-user push permissions with the same target/match model as access rules
- 📄 Inline diff viewer with side-by-side toggle; large diffs (>1000 lines) on a dedicated page
- 📦 Repository discovery with push/fetch traffic counts and one-click clone URL
- 🔌 Provider connectivity diagnostics (TCP, TLS, HTTP, git-specific probe)
- 🔄 Live config reload without server restart
Two modes, both active for every provider:
- Transparent proxy (
/proxy/<host>/...) — forwards the push to upstream via JettyProxyServlet. A servlet filter chain validates commits inline and rejects before the push reaches upstream. Developers re-push after fixing any validation failures and/or after a push is approved. - Store-and-forward (
/push/<host>/...) — runs as a live git server to receive the push locally, runs validation with real-time terminal feedback, then forwards upstream on approval. The push session stays open while a reviewer acts on the dashboard — no need to re-push after approval.
git remote add proxy http://localhost:8080/push/github.com/owner/repo.git
git push proxy mainSee the User Guide for URL scheme details, push modes, and the approval workflow.
mise install # Java 25 + Node 26 (or install manually)
git clone https://github.com/RBC/fogwall.git && cd fogwall
./gradlew build # compile + unit tests
./gradlew :fogwall-dashboard:run # proxy + dashboard at http://localhost:8080See CONTRIBUTING.md for detailed build instructions, Docker Compose setup, test scripts, and development workflow. See the Configuration Reference for YAML config, environment variable overrides, and provider settings.
| Provider | Identity resolution | Notes |
|---|---|---|
| GitHub | Token → user | github.com and GitHub Enterprise (custom URI) |
| GitLab | Token → user | gitlab.com and self-hosted instances |
| Bitbucket | Token → user | bitbucket.org and Bitbucket Data Center |
| Forgejo / Gitea | Token → user | Any Forgejo or Gitea instance |
Each provider can be pointed at a self-hosted instance via the uri config property. Multiple instances of the same
provider type are supported.
The dashboard supports multiple authentication backends:
| Provider | Description |
|---|---|
| Static (default) | Usernames and password hashes defined in YAML config |
| LDAP | Standard LDAP bind + optional group search |
| Active Directory | UPN bind via Spring's ActiveDirectoryLdapAuthenticationProvider |
| OIDC | OpenID Connect authorization code flow |
See the Configuration Reference for setup details. Docker Compose overlays are provided for LDAP and OIDC.
All pushes through the store-and-forward path are recorded as an event log. Each state transition (RECEIVED → APPROVED → FORWARDED, or BLOCKED/ERROR) is written as a separate row, enabling full push history and audit reporting.
| Type | Config value | Notes |
|---|---|---|
| H2 in-memory | h2-mem |
SQL schema, data lost on restart. Default. |
| H2 file | h2-file |
Persistent, zero external dependencies |
| PostgreSQL | postgres |
Production-grade |
| MongoDB | mongo |
Compatible with finos/git-proxy data model |
See the Configuration Reference for connection settings and Docker Compose profiles.
This is a multi-module Gradle project:
| Module | Purpose |
|---|---|
fogwall-core |
Shared library: filter chain, JGit hooks, push store, provider model, approval abstraction |
fogwall-server |
Standalone proxy-only server — no dashboard, no Spring |
fogwall-dashboard |
Dashboard + REST API — Spring MVC, approval UI, depends on fogwall-server |
| Document | Description |
|---|---|
| User Guide | For developers pushing code through the proxy: remote setup, push modes, blocked pushes, approval workflow |
| Administrator Guide | For operators: RBAC vs permissions, approval modes, logging, JGit filesystem requirements, production checklist |
| Configuration Reference | YAML config structure, environment variable overrides, provider settings, validation rules |
| Architecture | How the proxy works: two proxy modes, validation pipeline, core abstractions, advanced use cases |
| JGit Infrastructure | Store-and-forward internals: ReceivePackFactory, hook chain, forwarding, credential flow (contributor reference) |
| Git Internals | Wire-protocol edge cases: tags, new branches, force pushes, pack parsing (contributor reference) |
The backlog is tracked in GitHub Issues. The following gists cover design rationale and reference material:
| Document | Description |
|---|---|
| Background & architecture | Project background, relationship to finos/git-proxy, store-and-forward vs transparent proxy, near-term and moonshot roadmap |
| Programming model comparison | JGit + Jetty vs Express + child-process git: stack comparison, capability deep-dive, honest assessment of both sides |
| Performance benchmarks | Side-by-side comparison vs finos/git-proxy: sequential and concurrent clone, fetch, push throughput against a shared Gitea backend |
This project would not exist without FINOS git-proxy and its contributors, who designed the original push validation model, approval lifecycle, and multi-provider architecture. The Node.js implementation remains the reference for the Action/Step pipeline, Sink interface, and filter chain patterns that fogwall builds on. If you're in a Node.js environment, check out the original.
See CONTRIBUTING.md for how to build, run tests, use the manual test scripts in test/, and set up
the Docker Compose environment.