Intercepting a push

In this section, we will demonstrate the power 💪 of Git Proxy 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 Git Proxy

For demonstration purposes, we recommend forking Git Proxy 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 Git Proxy

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

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

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

Listening on 8000
Service Listening on 8080

Introduce Git Proxy to your clone

Navigate into your test-bed repository (where you cloned your Git Proxy 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 Git Proxy, run:

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

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 Git Proxy

git push

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

remote:
remote: Git Proxy has received your push:
remote: 
remote: http://localhost:8080/requests/000000__b12557    
remote:

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

Managing credentials

Git Proxy 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 Git Proxy, you will only require the public_repo scope.

Git Proxy 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

Git Proxy 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 Git Proxy installed.