Skip to content

Commit 53fcc3b

Browse files
JamieSlomeJamieSlome
authored
Merge pull request #323 from finos/321-bake-in-api-authorization-into-v110-documentation
2 parents 39c780f + 33ae1f4 commit 53fcc3b

File tree

9 files changed

+148
-55
lines changed

9 files changed

+148
-55
lines changed

‎README.md‎

Lines changed: 5 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -158,11 +158,11 @@ git config --global credential.helper store # Linux
158158
Immediately after a push, you should receive the following message in your terminal:
159159

160160
```bash
161-
remote: Git Proxy has received your push 🎉
162-
remote: ----------------------------------------------------------
163-
remote: Commit from | 000000
164-
remote: Commit to | b12557
165-
remote: URL | http://localhost:8080/push/000000__b12557
161+
remote:
162+
remote: Git Proxy has received your push:
163+
remote:
164+
remote: http://localhost:8080/requests/000000__b12557
165+
remote:
166166
```
167167

168168
## Configuring Git Proxy ⚙️

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

Lines changed: 7 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -2,9 +2,13 @@ const Step = require('../../actions').Step;
22

33
const exec = async (req, action) => {
44
const step = new Step('authBlock');
5-
step.setAsyncBlock(
6-
`Your push request is waiting authorisation, tracking id http://localhost:8080/requests/${action.id}`,
7-
);
5+
6+
const message =
7+
'\n\n\n' +
8+
`Git Proxy has received your push:\n\n` +
9+
`http://localhost:8080/requests/${action.id}` +
10+
'\n\n\n';
11+
step.setAsyncBlock(message);
812
action.addStep(step);
913
return action;
1014
};

website/docs/get-started/configuration.mdx renamed to website/docs/configuration.mdx

File renamed without changes.

website/docs/get-started/installation.mdx renamed to website/docs/installation.mdx

File renamed without changes.

‎website/docs/quickstart/approve.mdx‎

Lines changed: 82 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,82 @@
1+
---
2+
title: Approving a push
3+
description: How to approve a push in Git Proxy
4+
---
5+
6+
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.
7+
8+
## Using the REST API
9+
10+
### Prerequisites
11+
12+
- Proxy and REST API are running ([default behaviour](https://github.com/finos/git-proxy/blob/main/index.js))
13+
- Proxy and REST API are running on `localhost:8000` and `localhost:8080`, respectively
14+
- [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)
15+
- [`curl`](https://curl.se/) is installed
16+
17+
### Instructions
18+
19+
#### 1. Find the tracking `ID`
20+
21+
Following on from [Push via Git Proxy](/docs/quickstart/intercept#push-via-git-proxy), you'll receive a unique URL:
22+
23+
```
24+
http://localhost:8080/requests/0000000000000000000000000000000000000000__79b4d8953cbc324bcc1eb53d6412ff89666c241f
25+
```
26+
27+
The `ID` for your push corresponds to the last part of the URL:
28+
29+
```
30+
0000000000000000000000000000000000000000__79b4d8953cbc324bcc1eb53d6412ff89666c241f
31+
```
32+
33+
#### 2. Authenticate with the API
34+
35+
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`):
36+
37+
```bash
38+
curl -H "Content-Type: application/json" -c git-proxy-cookie -X POST \
39+
-d '{"username":"admin","password":"admin"}' http://localhost:8080/auth/login
40+
```
41+
42+
#### 3. Retrieve push with `ID` from database
43+
44+
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:
45+
46+
```bash
47+
curl -I -b ./git-proxy-cookie http://localhost:8080/api/v1/push/${ID}
48+
```
49+
50+
You should receive a `200 OK` in the response.
51+
52+
#### 4. Approve the push with `ID`
53+
54+
Using the same [cookie](/docs/quickstart/approve#2-authenticate-with-the-api) again, send a `POST` command to approve the push:
55+
56+
```bash
57+
curl -b ./git-proxy-cookie \
58+
-X POST http://localhost:8080/api/v1/push/${ID}/authorise
59+
```
60+
61+
#### 5. Re-push your code
62+
63+
Execute `git push` to send your approved code through Git Proxy to the upstream repository:
64+
65+
```bash
66+
$ git push
67+
Enumerating objects: 5, done.
68+
Counting objects: 100% (5/5), done.
69+
Delta compression using up to 10 threads
70+
Compressing objects: 100% (3/3), done.
71+
Writing objects: 100% (3/3), 470 bytes | 470.00 KiB/s, done.
72+
Total 3 (delta 2), reused 0 (delta 0), pack-reused 0
73+
remote: Resolving deltas: 100% (2/2), completed with 2 local objects.
74+
```
75+
76+
## Using the UI
77+
78+
:::note
79+
80+
The web UI is under active development. Keep an eye out for updates in our latest [releases](https://github.com/finos/git-proxy/releases).
81+
82+
:::

website/docs/get-started/quickstart.mdx renamed to website/docs/quickstart/intercept.mdx

Lines changed: 45 additions & 30 deletions
Original file line numberDiff line numberDiff line change
@@ -1,43 +1,55 @@
11
---
2-
title: Quickstart
3-
description: Ready to take Git Proxy for a test drive?
2+
title: Intercepting a push
3+
description: How to intercept a push with Git Proxy
44
---
55

6-
### 1. Create a simple configuration
6+
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:
77

8-
Create a configuration file in a workspace with the following JSON:
8+
### Prerequisites
99

10-
```json title="proxy.config.json"
10+
#### 1. Fork Git Proxy
11+
12+
For demonstration purposes, we recommend forking [Git Proxy](https://github.com/finos/git-proxy/fork) and then cloning the repository to your PC:
13+
14+
```bash
15+
git clone https://github.com/<YOUR-GITHUB-USERNAME>/git-proxy.git
16+
```
17+
18+
#### 2. Create a simple configuration
19+
20+
Create a configuration file in a new folder (separate to your fresh clone) with the following `JSON`:
21+
22+
```json title="new-folder/proxy.config.json"
1123
{
1224
"authorisedList": [
1325
{
1426
"project": "<YOUR-GITHUB-USERNAME>",
1527
"name": "git-proxy",
1628
"url": "https://github.com/<YOUR-GITHUB-USERNAME>/git-proxy.git"
1729
}
18-
],
30+
]
1931
}
2032
```
2133

22-
Then run Git Proxy and load the configuration file from your workspace:
34+
### Running Git Proxy
35+
36+
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:
2337

2438
```bash
25-
npx --package=@finos/git-proxy@1.1.0 -- git-proxy --config ./proxy.config.json
39+
npx --package=@finos/git-proxy@1.1.0 -- git-proxy --config ./new-folder/proxy.config.json
2640
```
2741

28-
### 2. Pick a repository
29-
30-
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.
31-
32-
For demonstration purposes, we recommend forking [Git Proxy](https://github.com/finos/git-proxy/fork) and cloning the repository to your PC:
42+
To confirm Git Proxy is running successfully, you should see the following in your terminal:
3343

3444
```bash
35-
git clone https://github.com/<YOUR-GITHUB-USERNAME>/git-proxy.git
45+
Listening on 8000
46+
Service Listening on 8080
3647
```
3748

38-
### 3. Introduce Git Proxy to your clone
3949

40-
Navigate into your test-bed repository on your PC:
50+
### Introduce Git Proxy to your clone
51+
52+
Navigate into your test-bed repository (where you cloned your Git Proxy fork) on your PC:
4153

4254
```bash
4355
cd ./git-proxy
@@ -46,7 +58,9 @@ cd ./git-proxy
4658
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:
4759

4860
```bash
61+
git remote -v
4962
git remote set-url origin http://localhost:8000/<YOUR-GITHUB-USERNAME>/git-proxy.git
63+
git remote -v
5064
```
5165

5266
:::note
@@ -55,7 +69,7 @@ SSH and HTTPS protocols are currently not supported. See [#27](https://github.co
5569

5670
:::
5771

58-
### 4. Make some changes to the codebase
72+
### Make changes to the codebase
5973

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

@@ -64,12 +78,25 @@ git add README.md
6478
git commit -m "chore: update README.md"
6579
```
6680

67-
### 5. Push your changes
81+
### Push via Git Proxy
6882

6983
```bash
7084
git push
7185
```
7286

87+
Immediately after a push, you should receive a message in your terminal:
88+
89+
```bash
90+
remote:
91+
remote: Git Proxy has received your push:
92+
remote:
93+
remote: http://localhost:8080/requests/000000__b12557
94+
remote:
95+
```
96+
97+
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.
98+
99+
73100
#### Managing credentials
74101

75102
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
90117

91118
:::
92119

93-
### 6. Eureka! 🎉
94-
95-
Immediately after a push, you should receive a message, like this, in your terminal:
96-
97-
```bash
98-
remote: Git Proxy has received your push 🎉
99-
remote: ----------------------------------------------------------
100-
remote: Commit from | 000000
101-
remote: Commit to | b12557
102-
remote: URL | http://localhost:8080/push/000000__b12557
103-
```
104-
105120

106121

website/docs/get-started/usage.mdx renamed to website/docs/usage.mdx

File renamed without changes.

‎website/sidebars.js‎

Lines changed: 8 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -3,28 +3,20 @@ module.exports = {
33
'index',
44
{
55
type: 'category',
6-
label: 'Get Started',
6+
label: 'Quickstart',
77
link: {
88
type: 'generated-index',
9-
title: 'Get Started',
10-
slug: '/category/get-started',
11-
keywords: [
12-
'get started',
13-
'quickstart',
14-
'installation',
15-
'configuration',
16-
'usage',
17-
],
9+
title: 'Quickstart',
10+
slug: '/category/quickstart',
11+
keywords: ['get started', 'quickstart'],
1812
image: '/img/github-mark.png',
1913
},
2014
collapsible: true,
2115
collapsed: false,
22-
items: [
23-
'get-started/installation',
24-
'get-started/usage',
25-
'get-started/configuration',
26-
'get-started/quickstart',
27-
],
16+
items: ['quickstart/intercept', 'quickstart/approve'],
2817
},
18+
'installation',
19+
'usage',
20+
'configuration',
2921
],
3022
};

‎website/src/pages/index.js‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -28,7 +28,7 @@ function Home() {
2828
</a>
2929
<a
3030
className="button button--outline button--secondary button--lg margin-left--sm"
31-
href="/docs/get-started/quickstart"
31+
href="/docs/category/quickstart"
3232
>
3333
Quickstart 🚀
3434
</a>

0 commit comments

Comments
 (0)