Deploy custom push protections and policies
on top of Git

Docs · Demo · Report a bug · Suggest a new feature

[![FINOS - Graduated](https://cdn.jsdelivr.net/gh/finos/contrib-toolbox@master/images/badge-graduated.svg)](https://community.finos.org/docs/governance/lifecycle-stages/graduated) [![NPM](https://img.shields.io/npm/v/@finos/git-proxy?colorA=00C586&colorB=000000)](https://www.npmjs.com/package/@finos/git-proxy) [![Build](https://img.shields.io/github/actions/workflow/status/finos/git-proxy/ci.yml?branch=main&label=CI&logo=github&colorA=00C586&colorB=000000)](https://github.com/finos/git-proxy/actions/workflows/ci.yml) [![codecov](https://codecov.io/gh/finos/git-proxy/branch/main/graph/badge.svg)](https://codecov.io/gh/finos/git-proxy) [![Documentation](https://img.shields.io/badge/_-documentation-000000?colorA=00C586&logo=docusaurus&logoColor=FFFFFF&)](https://git-proxy.finos.org)
[![License](https://img.shields.io/github/license/finos/git-proxy?colorA=00C586&colorB=000000)](https://github.com/finos/git-proxy/blob/main/LICENSE) [![Contributors](https://img.shields.io/github/contributors/finos/git-proxy?colorA=00C586&colorB=000000)](https://github.com/finos/git-proxy/graphs/contributors) [![Slack](https://img.shields.io/badge/_-Chat_on_Slack-000000.svg?logo=slack&colorA=00C586)](https://app.slack.com/client/T01E7QRQH97/C06LXNW0W76) [![git-proxy](https://api.securityscorecards.dev/projects/github.com/finos/git-proxy/badge)](https://api.securityscorecards.dev/projects/github.com/finos/git-proxy) [![OpenSSF Best Practices](https://www.bestpractices.dev/projects/10520/badge)](https://www.bestpractices.dev/projects/10520)

## What is GitProxy GitProxy is an application that stands between developers and a Git remote endpoint (e.g., `github.com`). It applies rules and workflows (configurable as `plugins`) to all outgoing `git push` operations to ensure they are compliant. GitProxy supports both **HTTP/HTTPS** and **SSH** protocols with identical security scanning and validation. The main goal of GitProxy is to marry the defacto standard Open Source developer experience (git-based workflow of branching out, submitting changes and merging back) with security and legal requirements that firms have to comply with, when operating in highly regulated industries like financial services. That said, GitProxy can also be used on a local environment to enforce a single developer's best practices, which tends to be the easiest setup to start with and the most comfortable one to build new GitProxy plugins. ```mermaid sequenceDiagram actor Developer Developer->>+Git Server: git clone Developer->>Workstation: git remote add proxy Developer->>+GitProxy: git push proxy GitProxy-->>-Developer: Failed license check Developer->>Workstation: git commit -m 'fix license issue' Developer->>+GitProxy: git push GitProxy-->>-Git Server: Approved ``` ## Getting Started 🚀 Install & run git-proxy (requires [Nodejs](https://nodejs.org/en/download/)): ```bash $ npx -- @finos/git-proxy ``` Clone a repository, set the remote to the GitProxy URL and push your changes: ### Using HTTPS ```bash $ git clone https://github.com/octocat/Hello-World.git && cd Hello-World # The below command is using the GitHub official CLI to fork the repo that is cloned. # You can also fork on the GitHub UI. For usage details on the CLI, see https://github.com/cli/cli $ gh repo fork ✓ Created fork yourGithubUser/Hello-World ... $ git remote add proxy http://localhost:8000/yourGithubUser/Hello-World.git # This fetches the repository's default branch and pushes it (https://stackoverflow.com/a/44750379). $ git push proxy $(git symbolic-ref refs/remotes/origin/HEAD | sed 's@^refs/remotes/origin/@@') ``` ### Using SSH ```bash $ git clone https://github.com/octocat/Hello-World.git && cd Hello-World $ gh repo fork ✓ Created fork yourGithubUser/Hello-World ... # Configure Git remote for SSH proxy $ git remote add proxy ssh://git@localhost:2222/github.com/yourGithubUser/Hello-World.git # Enable SSH agent forwarding (required) $ git config core.sshCommand "ssh -A" # Push through the proxy $ git push proxy $(git symbolic-ref refs/remotes/origin/HEAD | sed 's@^refs/remotes/origin/@@') ``` 📖 **Full SSH setup guide**: [docs/SSH_SETUP.md](docs/SSH_SETUP.md) --- Using the default configuration, GitProxy intercepts the push and _blocks_ it. To enable code pushing to your fork via GitProxy, add your repository URL into the GitProxy config file (`proxy.config.json`). For more information, refer to [our documentation](https://git-proxy.finos.org). ## Protocol Support GitProxy supports both **HTTP/HTTPS** and **SSH** protocols with identical security features: ### HTTP/HTTPS Support - ✅ Basic authentication and JWT tokens - ✅ Pack data extraction via middleware - ✅ Full security scanning and validation - ✅ Manual and auto-approval workflows ### SSH Support - ✅ SSH key-based authentication - ✅ SSH agent forwarding (uses client's SSH keys securely) - ✅ Pack data capture from SSH streams - ✅ Same 16-processor security chain as HTTPS - ✅ Complete feature parity with HTTPS Both protocols provide the same level of security scanning, including: - Secret detection (gitleaks) - Commit message and author validation - Hidden commit detection - Pre-receive hooks - Comprehensive audit logging ## Documentation For detailed step-by-step instructions for how to install, deploy & configure GitProxy and customize for your environment, see the [project's documentation](https://git-proxy.finos.org/docs/): - [Quickstart](https://git-proxy.finos.org/docs/category/quickstart/) - [Installation](https://git-proxy.finos.org/docs/quickstart/installation) - [Configuration](https://git-proxy.finos.org/docs/category/configuration) - [Contributing](https://git-proxy.finos.org/docs/development/contributing) - [Testing](https://github.com/finos/git-proxy/blob/main/CONTRIBUTING.md#testing) - [Architecture](https://git-proxy.finos.org/docs/category/architecture/) - [Upgrading to v2](https://git-proxy.finos.org/docs/upgrading-to-v2) ## Contributing Your contributions are at the core of making this a truly open source project. Any contributions you make are **greatly appreciated**. See [`CONTRIBUTING.md`](CONTRIBUTING.md) for more information. For AI-assisted development, start with [`AGENTS.md`](AGENTS.md). Tool-specific entry points are provided in [`CLAUDE.md`](CLAUDE.md), [`.cursor/rules/00-core.mdc`](.cursor/rules/00-core.mdc), and [`.github/copilot-instructions.md`](.github/copilot-instructions.md). Shared slash-command prompts live in [`.agents/commands`](.agents/commands), with tool-native entry points in [`.claude/commands`](.claude/commands) and [`.cursor/commands`](.cursor/commands). ## Security If you identify a security vulnerability in the codebase, please follow the steps in [`SECURITY.md`](https://github.com/finos/git-proxy/security/policy). This includes logic-based vulnerabilities and sensitive information or secrets found in code. ## Code of Conduct We are committed to making open source an enjoyable and respectful experience for our community. See [`CODE_OF_CONDUCT`](CODE_OF_CONDUCT.md) for more information. ## License This project is distributed under the Apache-2.0 license. See [`LICENSE`](LICENSE) for more information. ## Contact Drop a note, ask a question or just say hello in our community Slack channel [#git-proxy](https://finos-lf.slack.com/archives/C06LXNW0W76), which is accessible via the [FINOS Slack Workspace](https://finos-lf.slack.com) 👋 If you can't join, you can send us an e-mail to [help@finos.org](mailto:help@finos.org) to get access. You can also [subscribe to our mailing list](mailto:git-proxy+subscribe@lists.finos.org) and stay tuned for any updates 📨 Otherwise, if you have a deeper query or require more support, please [raise an issue](https://github.com/finos/git-proxy/issues) 🧵 🤝 Join our [fortnightly Zoom meeting](https://zoom-lfx.platform.linuxfoundation.org/meeting/95849833904?password=99413314-d03a-4b1c-b682-1ede2c399595) on Monday, 4PM BST (odd week numbers). 🌍 [Convert to your local time](https://www.timeanddate.com/worldclock) 📅 [Click here](https://zoom-lfx.platform.linuxfoundation.org/meeting/95849833904?password=99413314-d03a-4b1c-b682-1ede2c399595&invite=true) and complete the form to receive the recurring calendar meeting invite. Alternatively, send an e-mail to [help@finos.org](mailto:help@finos.org) requesting a calendar invitation.