diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 70cfa101..9570a7db 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -11,6 +11,9 @@ Before making a contribution, please take the following steps: 4. Fork the project repository and prepare your proposed contribution. 5. Submit a pull request. +If this is your first time contributing to open source projects on GitHub, it's recommended that you +follow the [contribution guide for first-time contributors](https://github.com/firstcontributions/first-contributions#first-contributions). + NOTE: All contributors must have a contributor license agreement (CLA) on file with FINOS before their pull requests will be merged. Please review the FINOS [contribution requirements](https://finosfoundation.atlassian.net/wiki/spaces/FINOS/pages/75530375/Contribution+Compliance+Requirements) and submit (or have your employer submit) the required CLA before submitting a pull request. ## Governance diff --git a/README.md b/README.md index cd60e2b0..bab49ce9 100644 --- a/README.md +++ b/README.md @@ -46,234 +46,40 @@ Git Proxy deploys custom push protections and policies on top of Git. It is a hi Git Proxy is built with a developer-first mindset. By presenting simple-to-follow remediation instructions in the CLI/Terminal, it minimises the friction of use and adoption, and keeps developers focused on what matters; committing and pushing code. -## Installation +## Getting Started 🚀 -To install Git Proxy, you must first install [Node.js](https://nodejs.org/en/download). Then, use the [npm](https://www.npmjs.com/) package manager: +Install & run git-proxy (requires [Nodejs](https://nodejs.org/en/download/)): ```bash -npm install -g @finos/git-proxy +$ npx -- @finos/git-proxy ``` -To install a specific version of Git Proxy, append the version to the end of the `install` command: +Clone a repository, set the remote to the Git Proxy URL and push your changes: ```bash -npm install -g @finos/git-proxy@1.1.0 +$ 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 +$ git push proxy master ``` -## Run Git Proxy ⚡ +Using the default configuration, Git Proxy intercepts the push and _blocks_ it. To enable code pushing to your fork via Git Proxy, add your repository URL into the Git Proxy config file (`proxy.config.json`). For more information, refer to [our documentation](https://git-proxy.finos.org). -Once you have followed the [installation](#installation) steps, run Git Proxy with: +## Documentation +For detailed step-by-step instructions for how to install, deploy & configure Git Proxy and +customize for your environment, see the [project's documentation](https://git-proxy.finos.org/docs/): -```bash -git-proxy -``` - -Alternatively, if you prefer the magic of [npx over npm](https://www.freecodecamp.org/news/npm-vs-npx-whats-the-difference/), you can run Git Proxy with: - -```bash -npx --package=@finos/git-proxy@1.1.0 -- git-proxy # No installation required... -``` - -## Quickstart 🚀 - -#### 1. Run Git Proxy with simple config - -Create a `proxy.config.json` in a workspace with the following: - -```json -{ - "authorisedList": [ - { - "project": "", - "name": "git-proxy", - "url": "https://github.com//git-proxy.git" - } - ], -} -``` - -Then run Git Proxy and load your `proxy.config.json` configuration file from your workspace: - -```bash -npx --package=@finos/git-proxy@1.1.0 -- git-proxy --config ./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: - -```bash -git clone https://github.com//git-proxy.git -``` - -Pretty meta, huh? Testing Git Proxy on Git Proxy... - -#### 3. Introduce Git Proxy to your clone - -Navigate into your test-bed repository on your PC: - -```bash -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 set-url origin http://localhost:8000//git-proxy.git -``` - -#### 4. Make some changes to the codebase - -Open up the `README.md` and turn this frown upside-down: ☚ī¸ - -Once you've cheered up our friend above, run: - -```bash -git add README.md -git commit -m "fix: turn frown upside-down" -``` - -#### 5. Push your changes via Git Proxy - -```bash -git push -``` - -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. - -Git Proxy will reprompt you for credentials each time you push. To automatically re-use your credentials, you can run: - -```bash -git config --global credential.helper osxkeychain # MacOS - -git config --global credential.helper manager # Windows - -git config --global credential.helper store # Linux -``` - -#### 6. Success - -Immediately after a push, you should receive the following message in your terminal: - -```bash -remote: -remote: Git Proxy has received your push: -remote: -remote: http://localhost:8080/requests/000000__b12557 -remote: -``` - -## Configuring Git Proxy ⚙ī¸ - -By default, Git Proxy ships with an out-of-the-box configuration. - -To customise your Git Proxy configuration, create a `proxy.config.json` in your directory. - -To specify a different file name for your Git Proxy configuration, use: - -```bash -git-proxy --config ./config.json -``` - -Or with npx: - -```bash -npx -- @finos/git-proxy --config ./config.json -``` - -## Know Your Configuration (KYC) ✅ - -To check that your Git Proxy configuration is valid, run: - -```bash -git-proxy --validate -``` - -To validate your configuration at a custom file location, run: - -```bash -git-proxy --validate --config ./config.json -``` +- [Quickstart](https://git-proxy.finos.org/docs/category/quickstart/) +- [Installation](https://git-proxy.finos.org/docs/installation) +- [Configuration](https://git-proxy.finos.org/docs/configuration) ## Contributing -Your contributions are at the core of making this a true open source project. Any contributions you make are **greatly appreciated**. - -
- - -fork this repository - - -#### Fork the repository - -Click on the **fork** button at the top of the page. This will create a copy of this repository under your GitHub account. - -
-
- -#### Clone the repository - -copy URL to clipboard - -**Clone** the repository to your machine. Go to the repository via your GitHub account and click on the **Code** button. - -Run the following command in your CLI/Terminal: - -```bash -git clone https://github.com/YOUR_GITHUB_USRERNAME/git-proxy.git -``` - -
-
- -#### Branch, code, commit and push - -
- -##### Branch - -You can start coding on the default branch on your fork of the project, commonly `master` or `main`. If you want to create a branch to clearly identify your work, run: - -```bash -git checkout -b feature/name-of-the-feature-you-are-creating -``` - -
- -##### Code - -This part is up to you. Be creative and write some magical code! 🧙đŸĒ„ - -
- -##### Commit - -Once you have finished making all of your improvements and changes, run the following: - -```bash -git commit -m "YOUR COMMIT MESSAGE" -``` - -
- -##### Push - -Now that you've created a commit with your changes, it's time to push to GitHub: - -```bash -git push -``` - -
- -##### Open a pull request - -With your changes applied to your fork of the project, it's time to [open a pull request from your repository](https://github.com/finos/git-proxy/compare)... - -
+Your contributions are at the core of making this a true open source project. Any contributions you make are **greatly appreciated**. See [`CONTRIBUTING.md`](CONTRIBUTING.md) for more information. ## Security @@ -290,4 +96,3 @@ This project is distributed under the Apache-2.0 license. See /g, '') + .replace(/# Git Proxy configuration file/g, '# Schema Reference'); // https://github.com/finos/git-proxy/pull/327#discussion_r1377343213 + const docString = `--- +title: Schema Reference +description: JSON schema reference documentation for Git Proxy +--- + +${schemaDoc} +`; + writeFileSync(OUTPUT_PATH, docString); + console.log(`Wrote schema reference to ${OUTPUT_PATH}`); +} catch (err) { + console.error(err); +} diff --git a/website/docs/configuration.mdx b/website/docs/configuration.mdx deleted file mode 100644 index 045b1c4b..00000000 --- a/website/docs/configuration.mdx +++ /dev/null @@ -1,43 +0,0 @@ ---- -title: Configuration -description: How to customise push protections and policies ---- - -### Default configuration - -On installation, Git Proxy ships with an out-of-the-box configuration. - -### Customise configuration - -To customise your Git Proxy configuration, create a `proxy.config.json` in your directory. - -### Alter the configuration path - -To specify a different file name for your Git Proxy configuration, use: - -```bash -git-proxy --config ./config.json -``` - -Or with npx: - -```bash -npx -- @finos/git-proxy --config ./config.json -``` - -### Validate configuration - -To validate your Git Proxy configuration, run: - -```bash -git-proxy --validate -``` - -To validate your configuration at a custom file location, run: - -```bash -git-proxy --validate --config ./config.json -``` - - - diff --git a/website/docs/configuration/overview.mdx b/website/docs/configuration/overview.mdx new file mode 100644 index 00000000..bf4987e4 --- /dev/null +++ b/website/docs/configuration/overview.mdx @@ -0,0 +1,61 @@ +--- +title: Overview +description: How to customise push protections and policies +--- + +### Default configuration + +On installation, Git Proxy ships with an [out-of-the-box configuration](https://github.com/finos/git-proxy/blob/main/proxy.config.json). This is fine for +demonstration purposes but is likely not what you want to deploy into your environment. +### Customise configuration + +To customise your Git Proxy configuration, create a `proxy.config.json` in your current +working directory. Git Proxy will load this file and set the values you have specified. Any +missing sections will use the default configuration values. + +Here is a minimal example: + +```json +{ + "authorisedList": [ + { + "project": "octocat", + "repo": "Hello-World", + "url": "https://github.com/octocat/Hello-World" + } + ] +} +``` + +The full configuration reference can be found at the [Reference page](/docs/configuration/reference/). + +### Alter the configuration path + +To specify a different file name for your Git Proxy configuration, use: + +```bash +git-proxy --config ./config.json +``` + +Or with npx: + +```bash +npx -- @finos/git-proxy --config ./config.json +``` + +### Validate configuration + +To validate your Git Proxy configuration, run: + +```bash +git-proxy --validate +``` + +To validate your configuration at a custom file location, run: + +```bash +git-proxy --validate --config ./config.json +``` + + + diff --git a/website/docs/configuration/reference.mdx b/website/docs/configuration/reference.mdx new file mode 100644 index 00000000..495f872c --- /dev/null +++ b/website/docs/configuration/reference.mdx @@ -0,0 +1,277 @@ +--- +title: Schema Reference +description: JSON schema reference documentation for Git Proxy +--- + +# Schema Reference + +**Title:** Git Proxy configuration file + +| | | +| ------------------------- | ------------------------------------------------------- | +| **Type** | `object` | +| **Required** | No | +| **Additional properties** | [[Not allowed]](# "Additional Properties not allowed.") | + +**Description:** Configuration for customizing git-proxy + +
+ 1. [Optional] Property Git Proxy configuration file > authorisedList +
+ +| | | +| ------------ | ------- | +| **Type** | `array` | +| **Required** | No | + +**Description:** List of repositories that are authorised to be pushed to through the proxy. + +| Each item of this array must be | Description | +| --------------------------------------- | ----------- | +| [authorisedRepo](#authorisedList_items) | - | + +### 1.1. Git Proxy configuration file > authorisedList > authorisedRepo + +| | | +| ------------------------- | ------------------------------------------------------------------------- | +| **Type** | `object` | +| **Required** | No | +| **Additional properties** | [[Any type: allowed]](# "Additional Properties of any type are allowed.") | +| **Defined in** | #/definitions/authorisedRepo | + +
+ 1.1.1. [Required] Property Git Proxy configuration file > authorisedList > authorisedList items > project +
+ +| | | +| ------------ | -------- | +| **Type** | `string` | +| **Required** | Yes | + +
+
+ +
+ 1.1.2. [Required] Property Git Proxy configuration file > authorisedList > authorisedList items > name +
+ +| | | +| ------------ | -------- | +| **Type** | `string` | +| **Required** | Yes | + +
+
+ +
+ 1.1.3. [Required] Property Git Proxy configuration file > authorisedList > authorisedList items > url +
+ +| | | +| ------------ | -------- | +| **Type** | `string` | +| **Required** | Yes | + +
+
+ +
+
+ +
+ 2. [Optional] Property Git Proxy configuration file > sink +
+ +| | | +| ------------ | ------- | +| **Type** | `array` | +| **Required** | No | + +**Description:** List of database sources. The first source in the configuration with enabled=true will be used. + +| Each item of this array must be | Description | +| ------------------------------- | ----------- | +| [database](#sink_items) | - | + +### 2.1. Git Proxy configuration file > sink > database + +| | | +| ------------------------- | ------------------------------------------------------------------------- | +| **Type** | `object` | +| **Required** | No | +| **Additional properties** | [[Any type: allowed]](# "Additional Properties of any type are allowed.") | +| **Defined in** | #/definitions/database | + +
+ 2.1.1. [Required] Property Git Proxy configuration file > sink > sink items > type +
+ +| | | +| ------------ | -------- | +| **Type** | `string` | +| **Required** | Yes | + +
+
+ +
+ 2.1.2. [Required] Property Git Proxy configuration file > sink > sink items > enabled +
+ +| | | +| ------------ | --------- | +| **Type** | `boolean` | +| **Required** | Yes | + +
+
+ +
+ 2.1.3. [Optional] Property Git Proxy configuration file > sink > sink items > connectionString +
+ +| | | +| ------------ | -------- | +| **Type** | `string` | +| **Required** | No | + +
+
+ +
+ 2.1.4. [Optional] Property Git Proxy configuration file > sink > sink items > options +
+ +| | | +| ------------------------- | ------------------------------------------------------------------------- | +| **Type** | `object` | +| **Required** | No | +| **Additional properties** | [[Any type: allowed]](# "Additional Properties of any type are allowed.") | + +
+
+ +
+ 2.1.5. [Optional] Property Git Proxy configuration file > sink > sink items > params +
+ +| | | +| ------------------------- | ------------------------------------------------------------------------- | +| **Type** | `object` | +| **Required** | No | +| **Additional properties** | [[Any type: allowed]](# "Additional Properties of any type are allowed.") | + +
+
+ +
+
+ +
+ 3. [Optional] Property Git Proxy configuration file > authentication +
+ +| | | +| ------------ | ------- | +| **Type** | `array` | +| **Required** | No | + +**Description:** List of authentication sources. The first source in the configuration with enabled=true will be used. + +| Each item of this array must be | Description | +| --------------------------------------- | ----------- | +| [authentication](#authentication_items) | - | + +### 3.1. Git Proxy configuration file > authentication > authentication + +| | | +| ------------------------- | ------------------------------------------------------------------------- | +| **Type** | `object` | +| **Required** | No | +| **Additional properties** | [[Any type: allowed]](# "Additional Properties of any type are allowed.") | +| **Defined in** | #/definitions/authentication | + +
+ 3.1.1. [Required] Property Git Proxy configuration file > authentication > authentication items > type +
+ +| | | +| ------------ | -------- | +| **Type** | `string` | +| **Required** | Yes | + +
+
+ +
+ 3.1.2. [Required] Property Git Proxy configuration file > authentication > authentication items > enabled +
+ +| | | +| ------------ | --------- | +| **Type** | `boolean` | +| **Required** | Yes | + +
+
+ +
+ 3.1.3. [Optional] Property Git Proxy configuration file > authentication > authentication items > options +
+ +| | | +| ------------------------- | ------------------------------------------------------------------------- | +| **Type** | `object` | +| **Required** | No | +| **Additional properties** | [[Any type: allowed]](# "Additional Properties of any type are allowed.") | + +
+
+ +
+
+ +
+ 4. [Optional] Property Git Proxy configuration file > tempPassword +
+ +| | | +| ------------------------- | ------------------------------------------------------------------------- | +| **Type** | `object` | +| **Required** | No | +| **Additional properties** | [[Any type: allowed]](# "Additional Properties of any type are allowed.") | + +**Description:** Toggle the generation of temporary password for git-proxy admin user + +
+ 4.1. [Optional] Property Git Proxy configuration file > tempPassword > sendEmail +
+ +| | | +| ------------ | --------- | +| **Type** | `boolean` | +| **Required** | No | + +
+
+ +
+ 4.2. [Optional] Property Git Proxy configuration file > tempPassword > emailConfig +
+ +| | | +| ------------------------- | ------------------------------------------------------------------------- | +| **Type** | `object` | +| **Required** | No | +| **Additional properties** | [[Any type: allowed]](# "Additional Properties of any type are allowed.") | + +**Description:** Generic object to configure nodemailer. For full type information, please see https://github.com/DefinitelyTyped/DefinitelyTyped/tree/master/types/nodemailer + +
+
+ +
+
+ +---------------------------------------------------------------------------------------------------------------------------- +Generated using [json-schema-for-humans](https://github.com/coveooss/json-schema-for-humans) on 2023-12-10 at 15:42:45 -0500 diff --git a/website/docs/quickstart/intercept.mdx b/website/docs/quickstart/intercept.mdx index 96edcec2..4b2f40f8 100644 --- a/website/docs/quickstart/intercept.mdx +++ b/website/docs/quickstart/intercept.mdx @@ -36,7 +36,7 @@ Create a configuration file in a new folder (separate to your fresh clone) with 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 ./new-folder/proxy.config.json +npx -- @finos/git-proxy --config ./new-folder/proxy.config.json ``` To confirm Git Proxy is running successfully, you should see the following in your terminal: diff --git a/website/docs/usage.mdx b/website/docs/usage.mdx index 6339c8d9..281deeb6 100644 --- a/website/docs/usage.mdx +++ b/website/docs/usage.mdx @@ -12,9 +12,9 @@ git-proxy ### Using [npx instead of npm](https://www.freecodecamp.org/news/npm-vs-npx-whats-the-difference/) -To directly run Git Proxy without any installation, run: +You can also install & run `git-proxy` in one step: ```bash -npx --package=@finos/git-proxy@1.1.0 -- git-proxy +npx -- @finos/git-proxy ``` diff --git a/website/sidebars.js b/website/sidebars.js index 5baee475..fb555b1d 100644 --- a/website/sidebars.js +++ b/website/sidebars.js @@ -17,6 +17,19 @@ module.exports = { }, 'installation', 'usage', - 'configuration', + { + type: 'category', + label: 'Configuration', + link: { + type: 'generated-index', + title: 'Configuration', + slug: '/category/configuration', + keywords: ['config', 'configuration'], + image: '/img/github-mark.png', + }, + collapsible: true, + collapsed: false, + items: ['configuration/overview', 'configuration/reference'], + }, ], };