Merge pull request #323 from finos/321-bake-in-api-authorization-into…

…-v110-documentation

README.md

@@ -158,11 +158,11 @@ git config --global credential.helper store # Linux
 Immediately after a push, you should receive the following message in your terminal:
 
 ```bash
-remote: Git Proxy has received your push 🎉
-remote: ----------------------------------------------------------
-remote:    Commit from | 000000
-remote:     Commit to  | b12557
-remote:        URL     | http://localhost:8080/push/000000__b12557    
+remote:
+remote: Git Proxy has received your push:
+remote: 
+remote: http://localhost:8080/requests/000000__b12557    
+remote:
 ```
 
 ## Configuring Git Proxy ⚙️

src/proxy/processors/push-action/blockForAuth.js

@@ -2,9 +2,13 @@ const Step = require('../../actions').Step;
 
 const exec = async (req, action) => {
   const step = new Step('authBlock');
-  step.setAsyncBlock(
-    `Your push request is waiting authorisation, tracking id http://localhost:8080/requests/${action.id}`,
-  );
+
+  const message =
+    '\n\n\n' +
+    `Git Proxy has received your push:\n\n` +
+    `http://localhost:8080/requests/${action.id}` +
+    '\n\n\n';
+  step.setAsyncBlock(message);
   action.addStep(step);
   return action;
 };

website/docs/quickstart/approve.mdx

@@ -0,0 +1,82 @@
+---
+title: Approving a push
+description: How to approve a push in Git Proxy
+---
+
+All pushes that flow through Git Proxy require an approval (authorisation). Until a push is approved, Git Proxy will block the commits from being sent to the upstream repository. To approve a push, you can use the REST API or web UI.
+
+## Using the REST API
+
+### Prerequisites
+
+- Proxy and REST API are running ([default behaviour](https://github.com/finos/git-proxy/blob/main/index.js))
+- Proxy and REST API are running on `localhost:8000` and `localhost:8080`, respectively
+- [Intercepting a push](/docs/quickstart/intercept) instructions have been followed and you've reached [Push via Git Proxy](/docs/quickstart/intercept#push-via-git-proxy)
+- [`curl`](https://curl.se/) is installed
+
+### Instructions
+
+#### 1. Find the tracking `ID`
+
+Following on from [Push via Git Proxy](/docs/quickstart/intercept#push-via-git-proxy), you'll receive a unique URL:
+
+```
+http://localhost:8080/requests/0000000000000000000000000000000000000000__79b4d8953cbc324bcc1eb53d6412ff89666c241f
+```
+
+The `ID` for your push corresponds to the last part of the URL:
+
+```
+0000000000000000000000000000000000000000__79b4d8953cbc324bcc1eb53d6412ff89666c241f
+```
+
+#### 2. Authenticate with the API
+
+Use the default & auto-generated Git Proxy username & password credentials to obtain a cookie. The cookie value is saved to a file (`git-proxy-cookie`):
+
+```bash
+curl -H "Content-Type: application/json" -c git-proxy-cookie -X POST \
+  -d '{"username":"admin","password":"admin"}' http://localhost:8080/auth/login
+```
+
+#### 3. Retrieve push with `ID` from database
+
+Using the [cookie](/docs/quickstart/approve#2-authenticate-with-the-api) generated, execute a `GET` request to confirm that your push with `ID` exists in the database:
+
+```bash
+curl -I -b ./git-proxy-cookie http://localhost:8080/api/v1/push/${ID}
+```
+
+You should receive a `200 OK` in the response.
+
+#### 4. Approve the push with `ID`
+
+Using the same [cookie](/docs/quickstart/approve#2-authenticate-with-the-api) again, send a `POST` command to approve the push:
+
+```bash
+curl -b ./git-proxy-cookie \
+  -X POST http://localhost:8080/api/v1/push/${ID}/authorise
+```
+
+#### 5. Re-push your code
+
+Execute `git push` to send your approved code through Git Proxy to the upstream repository:
+
+```bash
+$ git push
+Enumerating objects: 5, done.
+Counting objects: 100% (5/5), done.
+Delta compression using up to 10 threads
+Compressing objects: 100% (3/3), done.
+Writing objects: 100% (3/3), 470 bytes | 470.00 KiB/s, done.
+Total 3 (delta 2), reused 0 (delta 0), pack-reused 0
+remote: Resolving deltas: 100% (2/2), completed with 2 local objects.
+```
+
+## Using the UI
+
+:::note
+
+The web UI is under active development. Keep an eye out for updates in our latest [releases](https://github.com/finos/git-proxy/releases).
+
+:::

website/docs/get-started/quickstart.mdx → website/docs/quickstart/intercept.mdx

@@ -1,43 +1,55 @@
 ---
-title: Quickstart
-description: Ready to take Git Proxy for a test drive?
+title: Intercepting a push
+description: How to intercept a push with Git Proxy
 ---
 
-### 1. Create a simple configuration
+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:
 
-Create a configuration file in a workspace with the following JSON:
+### Prerequisites
 
-```json title="proxy.config.json"
+#### 1. Fork Git Proxy
+
+For demonstration purposes, we recommend forking [Git Proxy](https://github.com/finos/git-proxy/fork) and then cloning the repository to your PC:
+
+```bash
+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`:
+
+```json title="new-folder/proxy.config.json"
 {
   "authorisedList": [
     {
       "project": "<YOUR-GITHUB-USERNAME>",
       "name": "git-proxy",
       "url": "https://github.com/<YOUR-GITHUB-USERNAME>/git-proxy.git"
     }
-  ],
+  ]
 }
 ```
 
-Then run Git Proxy and load the configuration file from your workspace:
+### 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:
 
 ```bash
-npx --package=@finos/git-proxy@1.1.0 -- git-proxy --config ./proxy.config.json
+npx --package=@finos/git-proxy@1.1.0 -- git-proxy --config ./new-folder/proxy.config.json
 ```
 
-### 2. Pick a repository
-
-Git Proxy sits between the local clone of your repository and its remote upstream. Essentially, instead of communicating directly with the live version of your repository, you configure your local clone to speak with Git Proxy first.
-
-For demonstration purposes, we recommend forking [Git Proxy](https://github.com/finos/git-proxy/fork) and cloning the repository to your PC:
+To confirm Git Proxy is running successfully, you should see the following in your terminal:
 
 ```bash
-git clone https://github.com/<YOUR-GITHUB-USERNAME>/git-proxy.git
+Listening on 8000
+Service Listening on 8080
 ```
 
-### 3. Introduce Git Proxy to your clone
 
-Navigate into your test-bed repository on your PC:
+### Introduce Git Proxy to your clone
+
+Navigate into your test-bed repository (where you cloned your Git Proxy fork) on your PC:
 
 ```bash
 cd ./git-proxy
@@ -46,7 +58,9 @@ 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:
 
 ```bash
+git remote -v
 git remote set-url origin http://localhost:8000/<YOUR-GITHUB-USERNAME>/git-proxy.git
+git remote -v
 ```
 
 :::note
@@ -55,7 +69,7 @@ SSH and HTTPS protocols are currently not supported. See [#27](https://github.co
 
 :::
 
-### 4. Make some changes to the codebase
+### Make changes to the codebase
 
 Open up the `README.md` and make a change to the file.
 
@@ -64,12 +78,25 @@ git add README.md
 git commit -m "chore: update README.md"
 ```
 
-### 5. Push your changes
+### Push via Git Proxy
 
 ```bash
 git push
 ```
 
+Immediately after a push, you should receive a message in your terminal:
+
+```bash
+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](/docs/quickstart/approve) 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](https://github.com/settings/tokens). For the ability to push and pull code through Git Proxy, you will only require the `public_repo` scope.
@@ -90,17 +117,5 @@ Git Proxy **does not** use your Personal Access Token other than to authenticate
 
 :::
 
-### 6. Eureka! 🎉
-
-Immediately after a push, you should receive a message, like this, in your terminal:
-
-```bash
-remote: Git Proxy has received your push 🎉
-remote: ----------------------------------------------------------
-remote:    Commit from | 000000
-remote:     Commit to  | b12557
-remote:        URL     | http://localhost:8080/push/000000__b12557    
-```
-
 
 

website/sidebars.js

@@ -3,28 +3,20 @@ module.exports = {
     'index',
     {
       type: 'category',
-      label: 'Get Started',
+      label: 'Quickstart',
       link: {
         type: 'generated-index',
-        title: 'Get Started',
-        slug: '/category/get-started',
-        keywords: [
-          'get started',
-          'quickstart',
-          'installation',
-          'configuration',
-          'usage',
-        ],
+        title: 'Quickstart',
+        slug: '/category/quickstart',
+        keywords: ['get started', 'quickstart'],
         image: '/img/github-mark.png',
       },
       collapsible: true,
       collapsed: false,
-      items: [
-        'get-started/installation',
-        'get-started/usage',
-        'get-started/configuration',
-        'get-started/quickstart',
-      ],
+      items: ['quickstart/intercept', 'quickstart/approve'],
     },
+    'installation',
+    'usage',
+    'configuration',
   ],
 };

website/src/pages/index.js

@@ -28,7 +28,7 @@ function Home() {
             </a>
             <a
               className="button button--outline button--secondary button--lg margin-left--sm"
-              href="/docs/get-started/quickstart"
+              href="/docs/category/quickstart"
             >
               Quickstart 🚀
             </a>