Intercepting a push

In this section, we will demonstrate the power 💪 of GitProxy and how it works with a barebones & out-of-the-box demonstration using default configuration. Before we start, there are a few prerequisites:

Prerequisites

1. Fork GitProxy

For demonstration purposes, we recommend forking GitProxy and then cloning the repository to your PC:

git clone https://github.com/<YOUR-GITHUB-USERNAME>/git-proxy.git

2. Create a simple configuration

Create a configuration file in a new folder (separate to your fresh clone) with the following JSON:

new-folder/proxy.config.json

{
  "authorisedList": [
    {
      "project": "<YOUR-GITHUB-USERNAME>",
      "name": "git-proxy",
      "url": "https://github.com/<YOUR-GITHUB-USERNAME>/git-proxy.git"
    }
  ]
}

Running GitProxy

Now that you've got the prerequisites in place, it's time to run GitProxy and load the configuration file from your new folder:

npx -- @finos/git-proxy --config ./new-folder/proxy.config.json

To confirm GitProxy is running successfully, you should see the following in your terminal:

Listening on 8000
Service Listening on 8080

Introduce GitProxy to your clone

Navigate into your test-bed repository (where you cloned your GitProxy fork) on your PC:

cd ./git-proxy

By default the clone of your repository will communicate with GitHub. To change this, so that your local copy of the repository speaks with GitProxy, run:

git remote -v
git remote set-url origin http://localhost:8000/<YOUR-GITHUB-USERNAME>/git-proxy.git
git remote -v

You can also try HTTPS with git -c http.sslVerify=false remote set-url origin https://localhost:8443/<YOUR-GITHUB-USERNAME>/git-proxy.git

note

SSH protocol is currently not supported, see #27.

To simulate HTTPS connectivity, you can use ngrok (or similar tools) to create an HTTP/HTTPS public ingress and use its host to replace http://localhost:8080 in the git remote set-url command mentioned above.

Make changes to the codebase

Open up the README.md and make a change to the file.

git add README.md
git commit -m "chore: update README.md"

Push via GitProxy

git push

Immediately after a push, you should receive a message in your terminal:

remote:
remote: GitProxy has received your push ✅
remote:
remote: 🔗 Shareable Link
remote: http://localhost:8080/admin/push/000000__b12557
remote:

The push is now held in a suspended state by GitProxy and requires approval before it can be pushed to the upstream repository on GitHub.

Managing credentials

GitProxy will prompt the entry of your git credentials. These credentials are your GitHub username and a Personal Access Token. For the ability to push and pull code through GitProxy, you will only require the public_repo scope.

GitProxy will reprompt you for credentials each time you push. To automatically re-use your credentials, you can run:

git config --global credential.helper osxkeychain # MacOS

git config --global credential.helper manager # Windows

git config --global credential.helper store # Linux

info

GitProxy does not use your Personal Access Token other than to authenticate with GitHub when pushing code. This is identical to the process of pushing code to a repository without GitProxy installed.