+ 
@@ -92,7 +92,9 @@ customize for your environment, see the [project's documentation](https://git-pr - [Installation](https://git-proxy.finos.org/docs/quickstart/installation) - [Configuration](https://git-proxy.finos.org/docs/category/configuration) - [Contributing](https://git-proxy.finos.org/docs/development/contributing) -- [Testing](https://git-proxy.finos.org/docs/development/testing) +- [Testing](https://github.com/finos/git-proxy/blob/main/CONTRIBUTING.md#testing) +- [Architecture](https://git-proxy.finos.org/docs/category/architecture/) +- [Upgrading to v2](https://git-proxy.finos.org/docs/upgrading-to-v2) ## Contributing diff --git a/docs/img/logo.png b/docs/img/logo.png deleted file mode 100644 index d340cde5e..000000000 Binary files a/docs/img/logo.png and /dev/null differ diff --git a/experimental/license-inventory/README.md b/experimental/license-inventory/README.md index 0a4654aa8..363618559 100644 --- a/experimental/license-inventory/README.md +++ b/experimental/license-inventory/README.md @@ -1,7 +1,7 @@
- 
+ 
diff --git a/docs/Architecture.md b/website/docs/architecture/architecture.md similarity index 81% rename from docs/Architecture.md rename to website/docs/architecture/architecture.md index 7f49ebe62..e0d27df72 100644 --- a/docs/Architecture.md +++ b/website/docs/architecture/architecture.md @@ -2,7 +2,7 @@ This guide explains GitProxy's various components, and how they communicate with each other when performing a `git push`. -As mentioned in [the README](/README.md), GitProxy is an application that intercepts pushes and applies rules/policies to ensure they're compliant. Although a number of policies are available by default, these can be extended by using plugins. +As mentioned in [the README](https://github.com/finos/git-proxy/blob/main/README.md), GitProxy is an application that intercepts pushes and applies rules/policies to ensure they're compliant. Although a number of policies are available by default, these can be extended by using plugins. ## Overview @@ -10,12 +10,12 @@ GitProxy has several main components: - HTTP Proxy Express app (`/src/proxy`): The actual proxy server for Git. Git operations performed by users are intercepted here, processed by various Express middleware (such as URL rewriting) and applies the relevant **chain** of actions to the payload. Customized functionality in the form of **plugins** are inserted and added to this chain as well. - Chain: A set of **processors** that are applied to an action (i.e. a `git push` operation) before requesting review from a user with permission to approve pushes - - Processor: AKA `Step`. A specific step in the chain where certain rules are applied. See the [list of default processors](./Processors.md) for more details.` - - Plugin: A custom processor that can be added externally to extend GitProxy's default policies. See the [plugin guide](https://git-proxy.finos.org/docs/development/plugins) for more details. + - Processor: AKA `Step`. A specific step in the chain where certain rules are applied. See the [list of default processors](/docs/architecture/processors.md) for more details.` + - Plugin: A custom processor that can be added externally to extend GitProxy's default policies. See the [plugin guide](/docs/development/plugins) for more details. - Backend-for-frontend (BFF) Service API, Express app (`/src/service`): Handles UI requests, user authentication to GitProxy (not to Git), database operations and some of the logic for rejection/approval. Runs by default on port `8080`, and can be configured with the `GIT_PROXY_UI_HOST` and `GIT_PROXY_UI_PORT` environment variables. - Passport: The [library](https://www.passportjs.org/) used to authenticate to the GitProxy API (not the proxy itself - this depends on the Git `user.email`). Supports multiple authentication methods by default ([Local](#local), [AD](#activedirectory), [OIDC](#openid-connect)). - Routes: All the API endpoints used by the UI and proxy to perform operations and fetch or modify GitProxy's state. Except for custom plugin and processor development, there is no need for users or GitProxy administrators to interact with the API directly. -- Configuration (`/src/config`): Loads and validates the configuration from `proxy.config.json`, or any provided config file. Allows customising several aspects of GitProxy, including databases, authentication methods, predefined allowed repositories, commit blocking rules and more. For a full list of configurable parameters, check the [config file schema reference](https://git-proxy.finos.org/docs/configuration/reference/). +- Configuration (`/src/config`): Loads and validates the configuration from `proxy.config.json`, or any provided config file. Allows customising several aspects of GitProxy, including databases, authentication methods, predefined allowed repositories, commit blocking rules and more. For a full list of configurable parameters, check the [config file schema reference](/docs/configuration/reference/). - Web UI, React (`/src/ui`): Allows user-friendly interactions with the application. Shows the list of pushes requiring approval, the list of repositories that users can contribute to, and more. Also allows users to easily review the changes in a push, and approve or reject it manually according to company policy. ## Diagram @@ -24,11 +24,11 @@ These are all the core components in the project, along with some basic user int - + ### Pushing to GitProxy @@ -53,18 +53,18 @@ Don't forget to save and update the attached .drawio (XML)! --> Three types of policies can be applied to incoming pushes: - Default policies: These are already present in the GitProxy pull/push chain and require modifying source code to change their behaviour. - - For example, [`checkUserPushPermission`](./Processors.md#checkuserpushpermission) which simply checks if the pusher's email exists in the GitProxy database, and if their user is marked in the "Contributors" list (`canPush`) for the repository they're trying to push to. + - For example, [`checkUserPushPermission`](/docs/architecture/processors.md#checkuserpushpermission) which simply checks if the pusher's email exists in the GitProxy database, and if their user is marked in the "Contributors" list (`canPush`) for the repository they're trying to push to. - Configurable policies: These are policies that can be easily configured through the GitProxy config (`proxy.config.json` or a custom file). - - For example, [`checkCommitMessages`](./Processors.md#checkcommitmessages) which reads the configuration and matches the string patterns provided with the commit messages in the push in order to block it. + - For example, [`checkCommitMessages`](/docs/architecture/processors.md#checkcommitmessages) which reads the configuration and matches the string patterns provided with the commit messages in the push in order to block it. - Custom policies: - - Plugins: Push/pull plugins provide more flexibility for implementing an organization's rules. For more information, see the [guide on writing your own plugins](https://git-proxy.finos.org/docs/development/plugins). + - Plugins: Push/pull plugins provide more flexibility for implementing an organization's rules. For more information, see the [guide on writing your own plugins](/docs/development/plugins). - Processors: Custom logic may require specific data within a push that isn't available at the end of the chain (where plugins are executed). In this case, the appropriate solution is to write a processor and add it to the correct place in the chain. ## The nitty gritty ### Pre-processors -Pre-processors run before executing the chain. Currently, only executes [`parseAction`](./Processors.md#parseaction), which is in charge of classifying requests as push/pull/default and creating the `Action` object used by the chain. +Pre-processors run before executing the chain. Currently, only executes [`parseAction`](/docs/architecture/processors.md#parseaction), which is in charge of classifying requests as push/pull/default and creating the `Action` object used by the chain. ### Action Chains @@ -74,27 +74,27 @@ Action chains are a list of processors that a Git operation goes through before Executed when a user makes a `git push` to GitProxy. These are the actions in `pushActionChain`, by order of execution: -- [`parsePush`](./Processors.md#parsepush) -- [`checkEmptyBranch`](./Processors.md#checkemptybranch) -- [`checkRepoInAuthorisedList`](./Processors.md#checkrepoinauthorisedlist) -- [`checkCommitMessages`](./Processors.md#checkcommitmessages) -- [`checkAuthorEmails`](./Processors.md#checkauthoremails) -- [`checkUserPushPermission`](./Processors.md#checkuserpushpermission) -- [`pullRemote`](./Processors.md#pullremote) -- [`writePack`](./Processors.md#writepack) -- [`checkHiddenCommits`](./Processors.md#checkhiddencommits) -- [`checkIfWaitingAuth`](./Processors.md#checkifwaitingauth) -- [`preReceive`](./Processors.md#prereceive) -- [`getDiff`](./Processors.md#getdiff) -- [`gitleaks`](./Processors.md#gitleaks) -- [`scanDiff`](./Processors.md#scandiff) -- [`blockForAuth`](./Processors.md#blockforauth) +- [`parsePush`](/docs/architecture/processors.md#parsepush) +- [`checkEmptyBranch`](/docs/architecture/processors.md#checkemptybranch) +- [`checkRepoInAuthorisedList`](/docs/architecture/processors.md#checkrepoinauthorisedlist) +- [`checkCommitMessages`](/docs/architecture/processors.md#checkcommitmessages) +- [`checkAuthorEmails`](/docs/architecture/processors.md#checkauthoremails) +- [`checkUserPushPermission`](/docs/architecture/processors.md#checkuserpushpermission) +- [`pullRemote`](/docs/architecture/processors.md#pullremote) +- [`writePack`](/docs/architecture/processors.md#writepack) +- [`checkHiddenCommits`](/docs/architecture/processors.md#checkhiddencommits) +- [`checkIfWaitingAuth`](/docs/architecture/processors.md#checkifwaitingauth) +- [`preReceive`](/docs/architecture/processors.md#prereceive) +- [`getDiff`](/docs/architecture/processors.md#getdiff) +- [`gitleaks`](/docs/architecture/processors.md#gitleaks) +- [`scanDiff`](/docs/architecture/processors.md#scandiff) +- [`blockForAuth`](/docs/architecture/processors.md#blockforauth) #### Pull action chain Executed when a user makes a `git clone` or `git pull` to GitProxy: -- [`checkRepoInAuthorisedList`](./Processors.md#checkrepoinauthorisedlist) +- [`checkRepoInAuthorisedList`](/docs/architecture/processors.md#checkrepoinauthorisedlist) At present, the pull action chain is only checking that the repository is configured in GitProxy. This ensures it will block pull requests for unknown repositories. @@ -102,17 +102,17 @@ At present, the pull action chain is only checking that the repository is config This chain is executed when making any operation other than a `git push` or `git pull`. -- [`checkRepoInAuthorisedList`](./Processors.md#checkrepoinauthorisedlist) +- [`checkRepoInAuthorisedList`](/docs/architecture/processors.md#checkrepoinauthorisedlist) The default action chain, much like the pull chain, is only checking that the repository is configured in GitProxy. This ensures it will block all git client requests for unknown repositories. ### Post-processors -After processors in the chain are done executing, [`audit`](./Processors.md#audit) is called to store the action along with all of its execution steps in the database for auditing purposes. +After processors in the chain are done executing, [`audit`](/docs/architecture/processors.md#audit) is called to store the action along with all of its execution steps in the database for auditing purposes. -If [`pullRemote`](./Processors.md#pullremote) ran successfully and cloned the repository, then [`clearBareClone`](./Processors.md#clearbareclone) is run to clear up that clone, freeing disk space and ensuring that the _.remote/\*_ folder created does not conflict with any future pushes involving the same SHA. +If [`pullRemote`](/docs/architecture/processors.md#pullremote) ran successfully and cloned the repository, then [`clearBareClone`](/docs/architecture/processors.md#clearbareclone) is run to clear up that clone, freeing disk space and ensuring that the _.remote/\*_ folder created does not conflict with any future pushes involving the same SHA. -Finally, if the action was auto-approved or auto-rejected as a result of running [`preReceive`](./Processors.md#prereceive), it will attempt to auto-approve or auto-reject it. +Finally, if the action was auto-approved or auto-rejected as a result of running [`preReceive`](/docs/architecture/processors.md#prereceive), it will attempt to auto-approve or auto-reject it. ### Authentication @@ -175,7 +175,7 @@ For example: logging in with myusername@mymail.com will create a new user with u New methods can be added by: 1. Extending `/src/service/passport` with the relevant [passport.js strategy](https://www.passportjs.org/packages/). - - The strategy file must have a `configure` method and a `type` string to match with the config method. See the pre-existing methods in [`/src/service/passport`](/src/service/passport) for more details. + - The strategy file must have a `configure` method and a `type` string to match with the config method. See the pre-existing methods in [`/src/service/passport`](https://github.com/finos/git-proxy/blob/main/src/service/passport) for more details. 2. Creating a `proxy.config.json` entry with the required configuration parameters 3. Importing the new strategy and adding it to the `authStrategies` array in `/src/service/passport/index.ts` @@ -224,7 +224,7 @@ Currently supports the following out-of-the-box: #### `commitConfig` -Used in [`checkCommitMessages`](./Processors.md#checkcommitmessages), [`checkAuthorEmails`](./Processors.md#checkauthoremails) and [`scanDiff`](./Processors.md#scandiff) processors to block pushes depending on the given rules. +Used in [`checkCommitMessages`](/docs/architecture/processors.md#checkcommitmessages), [`checkAuthorEmails`](/docs/architecture/processors.md#checkauthoremails) and [`scanDiff`](/docs/architecture/processors.md#scandiff) processors to block pushes depending on the given rules. By default, no rules are applied. @@ -310,13 +310,13 @@ Has a list of `questions`, each of which can be configured with a `label` and a Given the previous configuration, the attestation prompt would look like this: - + #### `domains` Allows setting custom URLs for GitProxy interfaces in case these cannot be determined. -This parameter is used in [`/src/service/urls.ts`](/src/service/urls.ts) to override URLs for the proxy (default: http://localhost:8000) and service (default: http://localhost:8080). +This parameter is used in [`/src/service/urls.ts`](https://github.com/finos/git-proxy/blob/main/src/service/urls.ts) to override URLs for the proxy (default: http://localhost:8000) and service (default: http://localhost:8080). Sample configuration: @@ -356,7 +356,7 @@ Currently unused. Sets the contact email for the Open Source Program Office (or equivalent organisational contact) in the attestation form: - + #### `csrfProtection` @@ -416,7 +416,7 @@ List of database sources. The first source with `enabled` set to `true` will be Each entry has its own unique configuration parameters. -Extending GitProxy to support other databases requires adding the relevant handlers and setup to the [`/src/db`](/src/db/) directory. Feel free to [open an issue](https://github.com/finos/git-proxy/issues) requesting support for any specific databases - or [open a PR](https://github.com/finos/git-proxy/pulls) with the desired changes! +Extending GitProxy to support other databases requires adding the relevant handlers and setup to the [`/src/db`](https://github.com/finos/git-proxy/blob/main/src/db/) directory. Feel free to [open an issue](https://github.com/finos/git-proxy/issues) requesting support for any specific databases - or [open a PR](https://github.com/finos/git-proxy/pulls) with the desired changes! #### `authentication` @@ -432,7 +432,7 @@ Allows defining ways to authenticate to the API. This is useful for securing cus If `apiAuthentication` is left empty, API endpoints will be publicly accesible. -Currently, only JWT auth is supported. This is implemented via the [`jwtAuthHandler` middleware](/src/service/passport/jwtAuthHandler.ts). Aside of validating incoming access tokens, it can also assign roles based on the token payload. +Currently, only JWT auth is supported. This is implemented via the [`jwtAuthHandler` middleware](https://github.com/finos/git-proxy/blob/main/src/service/passport/jwtAuthHandler.ts). Aside of validating incoming access tokens, it can also assign roles based on the token payload. ##### Setting up JWT Authentication diff --git a/docs/Processors.md b/website/docs/architecture/processors.md similarity index 85% rename from docs/Processors.md rename to website/docs/architecture/processors.md index de5bcb696..8f4edc590 100644 --- a/docs/Processors.md +++ b/website/docs/architecture/processors.md @@ -14,7 +14,7 @@ This action also handles fallbacks for v1 legacy proxy URLs. Checks if the URL of the repo being pushed to is present in the GitProxy repo database. If no repo URL in the database matches, the push is blocked. -Source: [/src/proxy/processors/push-action/checkRepoInAuthorisedList.ts](/src/proxy/processors/push-action/checkRepoInAuthorisedList.ts) +Source: [/src/proxy/processors/push-action/checkRepoInAuthorisedList.ts](https://github.com/finos/git-proxy/blob/main/src/proxy/processors/push-action/checkRepoInAuthorisedList.ts) ## `parsePush` @@ -22,13 +22,13 @@ Parses the push request data which comes from the Git client as a buffer that co Also handles extraction of push contents, such as the details of the individual commits contained in the push and the details of `committer` (the user attempting to push the commits through the proxy). -Source: [/src/proxy/processors/push-action/parsePush.ts](/src/proxy/processors/push-action/parsePush.ts) +Source: [/src/proxy/processors/push-action/parsePush.ts](https://github.com/finos/git-proxy/blob/main/src/proxy/processors/push-action/parsePush.ts) ## `checkEmptyBranch` Checks if the push contains any commit data, or is just an empty branch push (pushing a new branch without any additional commits). Empty branch pushes are blocked because subsequent processors require commit data to work correctly. -Source: [/src/proxy/processors/push-action/checkEmptyBranch.ts](/src/proxy/processors/push-action/checkEmptyBranch.ts) +Source: [/src/proxy/processors/push-action/checkEmptyBranch.ts](https://github.com/finos/git-proxy/blob/main/src/proxy/processors/push-action/checkEmptyBranch.ts) ## `checkCommitMessages` @@ -66,7 +66,7 @@ If the arrays are empty, the checks will pass and chain execution will continue. Note that invalid regex patterns will throw an error during proxy startup. These must be fixed in order to initialize GitProxy. -Source: [/src/proxy/processors/push-action/checkCommitMessages.ts](/src/proxy/processors/push-action/checkCommitMessages.ts) +Source: [/src/proxy/processors/push-action/checkCommitMessages.ts](https://github.com/finos/git-proxy/blob/main/src/proxy/processors/push-action/checkCommitMessages.ts) ## `checkAuthorEmails` @@ -76,7 +76,7 @@ If neither of these are configured (set to empty strings), then the checks will Note that invalid regex patterns will throw an error during proxy startup. These must be fixed in order to initialize GitProxy. -Source: [/src/proxy/processors/push-action/checkAuthorEmails.ts](/src/proxy/processors/push-action/checkAuthorEmails.ts) +Source: [/src/proxy/processors/push-action/checkAuthorEmails.ts](https://github.com/finos/git-proxy/blob/main/src/proxy/processors/push-action/checkAuthorEmails.ts) #### `checkUserPushPermission` @@ -90,7 +90,7 @@ This step will fail on various scenarios such as: Note: The _pusher_ can potentially be a different user from the _commit author(s)_. In order to filter the commit authors, you must use the `commitConfig.author` config entry. See [`checkAuthorEmails`](#checkauthoremails) for more details. -Source: [/src/proxy/processors/push-action/checkUserPushPermission.ts](/src/proxy/processors/push-action/checkUserPushPermission.ts) +Source: [/src/proxy/processors/push-action/checkUserPushPermission.ts](https://github.com/finos/git-proxy/blob/main/src/proxy/processors/push-action/checkUserPushPermission.ts) ## `pullRemote` @@ -102,7 +102,7 @@ In the event that the clone fails, pullRemote will automatically delete the _.re If the clone succeeds then the chain will schedule deletion of the clone by [`clearBareClone`](#clearbareclone) after processing of the chain completes. This ensures that disk space used is recovered, subsequent pushes of the same SHA don't conflict and that user credentials cached in the `git clone` are removed. -Source: [/src/proxy/processors/push-action/pullRemote.ts](/src/proxy/processors/push-action/pullRemote.ts) +Source: [/src/proxy/processors/push-action/pullRemote.ts](https://github.com/finos/git-proxy/blob/main/src/proxy/processors/push-action/pullRemote.ts) ## `writePack` @@ -110,7 +110,7 @@ Executes `git receive-pack` with the incoming pack data from the request body in Note that `writePack` sets Git's `receive.unpackLimit` to `0`, which forces Git to always create pack files instead of unpacking objects individually. -Source: [/src/proxy/processors/push-action/writePack.ts](/src/proxy/processors/push-action/writePack.ts) +Source: [/src/proxy/processors/push-action/writePack.ts](https://github.com/finos/git-proxy/blob/main/src/proxy/processors/push-action/writePack.ts) ## `checkHiddenCommits` @@ -118,13 +118,13 @@ Detects "hidden" commits in a push, which is possible if the pack file in the pu It calls `git verify-pack` on each of the new `.idx` files found in [`writePack`](#writepack). If any unreferenced commits are present, the push is blocked. -Source: [/src/proxy/processors/push-action/checkHiddenCommits.ts](/src/proxy/processors/push-action/checkHiddenCommits.ts) +Source: [/src/proxy/processors/push-action/checkHiddenCommits.ts](https://github.com/finos/git-proxy/blob/main/src/proxy/processors/push-action/checkHiddenCommits.ts) ## `checkIfWaitingAuth` Checks if the action has been authorised (approved by a reviewer). If so, allows the push to continue to the remote. It simply continues chain execution if the push hasn't been approved. -Source: [/src/proxy/processors/push-action/checkIfWaitingAuth.ts](/src/proxy/processors/push-action/checkIfWaitingAuth.ts) +Source: [/src/proxy/processors/push-action/checkIfWaitingAuth.ts](https://github.com/finos/git-proxy/blob/main/src/proxy/processors/push-action/checkIfWaitingAuth.ts) ## `preReceive` @@ -142,7 +142,7 @@ This processor will block the push depending on the exit status of the pre-recei For detailed setup instructions and examples, see the [Pre-Receive Hook configuration guide](https://git-proxy.finos.org/docs/configuration/pre-receive/). -Source: [/src/proxy/processors/push-action/preReceive.ts](/src/proxy/processors/push-action/preReceive.ts) +Source: [/src/proxy/processors/push-action/preReceive.ts](https://github.com/finos/git-proxy/blob/main/src/proxy/processors/push-action/preReceive.ts) ## `getDiff` @@ -150,7 +150,7 @@ Executes `git diff` to obtain the diff for the given revision range. If there ar The data extracted in this step is later used in [`scanDiff`](#scandiff). -Source: [/src/proxy/processors/push-action/getDiff.ts](/src/proxy/processors/push-action/getDiff.ts) +Source: [/src/proxy/processors/push-action/getDiff.ts](https://github.com/finos/git-proxy/blob/main/src/proxy/processors/push-action/getDiff.ts) ## `gitleaks` @@ -165,7 +165,7 @@ The following parameters can be configured: This processor runs the Gitleaks check starting from the root commit to the `commitFrom` value present in the push. If the Gitleaks check fails (nonzero exit code), or otherwise cannot spawn, the push will be blocked. -Source: [/src/proxy/processors/push-action/gitleaks.ts](/src/proxy/processors/push-action/gitleaks.ts) +Source: [/src/proxy/processors/push-action/gitleaks.ts](https://github.com/finos/git-proxy/blob/main/src/proxy/processors/push-action/gitleaks.ts) ## `scanDiff` @@ -203,7 +203,7 @@ This will scan every file changed and try to match the configured literals, patt Note that invalid regex patterns will throw an error during proxy startup. These must be fixed in order to initialize GitProxy. -Source: [/src/proxy/processors/push-action/scanDiff.ts](/src/proxy/processors/push-action/scanDiff.ts) +Source: [/src/proxy/processors/push-action/scanDiff.ts](https://github.com/finos/git-proxy/blob/main/src/proxy/processors/push-action/scanDiff.ts) ## `blockForAuth` @@ -211,9 +211,9 @@ This action appends a message to be displayed after all the processors have fini Note that this message will show again even if the push had been previously rejected by a reviewer or cancelled and resubmitted by the committer. After a manual rejection, pushing again creates a new `action` object so that the push can be re-reviewed and approved. - + -Source: [/src/proxy/processors/push-action/blockForAuth.ts](/src/proxy/processors/push-action/blockForAuth.ts) +Source: [/src/proxy/processors/push-action/blockForAuth.ts](https://github.com/finos/git-proxy/blob/main/src/proxy/processors/push-action/blockForAuth.ts) ## `audit` @@ -284,4 +284,4 @@ Recursively removes the contents of the (modified) repository clone stored in `. `clearBareClone` runs only if `pullRemote` was successful. -Source: [/src/proxy/processors/post-processor/clearBareClone.ts](/src/proxy/processors/post-processor/clearBareClone.ts) +Source: [/src/proxy/processors/post-processor/clearBareClone.ts](https://github.com/finos/git-proxy/blob/main/src/proxy/processors/post-processor/clearBareClone.ts) diff --git a/website/docs/deployment.mdx b/website/docs/deployment.mdx index 70479a901..bfc5a549f 100644 --- a/website/docs/deployment.mdx +++ b/website/docs/deployment.mdx @@ -126,7 +126,7 @@ remote: http://localhost:8080/dashboard/push/000000__b12557 - Username: `admin` - Password: `admin` - See the [Authentication](https://github.com/finos/git-proxy/blob/main/docs/Architecture.md#authentication) section of the architecture guide for more details. + See the [Authentication](/docs/architecture/architecture.md#authentication) section of the architecture guide for more details. 3. Review the push and approve it 4. Push again to forward to upstream: ```bash diff --git a/docs/Upgrading to v2.md b/website/docs/upgrading-to-v2.md similarity index 97% rename from docs/Upgrading to v2.md rename to website/docs/upgrading-to-v2.md index 1443eae10..fc94dcee5 100644 --- a/docs/Upgrading to v2.md +++ b/website/docs/upgrading-to-v2.md @@ -10,7 +10,7 @@ Two important breaking changes were made: ### Associate commits by email -Commits are no longer associated by Git's `user.name`. Now, they're associated by email (to match the handling of commits by GitHub, GitLab and other SCM providers), which allows Git Proxy to handle multiple SCM providers. [#973](github.com/finos/git-proxy/pull/973) +Commits are no longer associated by Git's `user.name`. Now, they're associated by email (to match the handling of commits by GitHub, GitLab and other SCM providers), which allows Git Proxy to handle multiple SCM providers. [#973](https://github.com/finos/git-proxy/pull/973) In practice, pushes that were working in v1 (made with an improperly configured git client) may be blocked in v2 due to the change in requirements. The user's GitProxy email must match the commit's email (Git's `user.email`). This is often already required by a firm's contribution policy or to pass a CLA (Contributor License Agreement) check on a project. @@ -30,7 +30,7 @@ If you encounter any errors not on this guide, feel free to [open a discussion]( ### Errors when pushing to a repo that was working in v1: -#### fatal:/info/refs not valid: is this git repository?
+#### fatal: ``/info/refs not valid: is this git repository?
`git push` returns:
@@ -52,7 +52,7 @@ In v2, URLs are automatically formatted when adding a repo. **Repos added in v1
"url": "https://github.com/my-org/my-repo.git"
```
-#### Your push has been blocked ( is not allowed to push on repo )
+#### Your push has been blocked (`` is not allowed to push on repo ``)
`git push` returns:
@@ -93,7 +93,7 @@ Changing the email address associated with commits can be accomplished via a num
- `checkEmptyBranch` simply checks whether the branch has had any new commits (if not, the push will be rejected)
- Added a settings page for configuring the JWT token to authenticate UI requests to API when `apiAuthentication` is enabled in [#1096](https://github.com/finos/git-proxy/pull/1096)
- Previously, requests from the UI were bypassing the JWT check if the user was logged in, and failing otherwise when `apiAuthentication` was set
- - For more details on setting JWT, check the [architecture documentation](./Architecture.md#setting-up-jwt-authentication):
+ - For more details on setting JWT, check the [architecture documentation](/docs/architecture/architecture.md#setting-up-jwt-authentication):
- Added the ability to create new users via the GitProxy CLI in [#981](https://github.com/finos/git-proxy/pull/981)
- Added `/healthcheck` endpoint for AWS Load Balancer support [#1197](https://github.com/finos/git-proxy/pull/1197)
- Improved login page flexibility, error handling and visibility of available auth methods in [#1227](https://github.com/finos/git-proxy/pull/1227)
diff --git a/website/package.json b/website/package.json
index 7ad579179..758b5c33c 100644
--- a/website/package.json
+++ b/website/package.json
@@ -17,8 +17,8 @@
"axios": "^1.13.4",
"classnames": "^2.5.1",
"clsx": "^2.1.1",
- "eslint": "^9.39.2",
- "eslint-plugin-react": "^7.37.5",
+ "eslint": "^10.1.0",
+ "eslint-plugin-react": "^7.22.0",
"react": "^19.2.4",
"react-dom": "^19.2.4",
"react-player": "^3.4.0",
@@ -40,6 +40,7 @@
]
},
"overrides": {
+ "lodash": "^4.18.0",
"serialize-javascript": "^7.0.5",
"uuid": "^14.0.0",
"webpack": "~5.105.0"
diff --git a/website/sidebars.js b/website/sidebars.js
index df341fe77..c762c5079 100644
--- a/website/sidebars.js
+++ b/website/sidebars.js
@@ -36,6 +36,8 @@ module.exports = {
'quickstart/approve',
],
},
+ 'deployment',
+ 'upgrading-to-v2',
{
type: 'category',
label: 'Configuration',
@@ -50,7 +52,20 @@ module.exports = {
collapsed: false,
items: ['configuration/overview', 'configuration/reference', 'configuration/pre-receive'],
},
- 'deployment',
+ {
+ type: 'category',
+ label: 'Architecture',
+ link: {
+ type: 'generated-index',
+ title: 'Architecture',
+ slug: '/category/architecture',
+ keywords: ['architecture'],
+ image: '/img/github-mark.png',
+ },
+ collapsible: true,
+ collapsed: false,
+ items: ['architecture/architecture', 'architecture/processors'],
+ },
{
type: 'category',
label: 'Development',
diff --git a/docs/img/GitProxy_Architecture.drawio b/website/static/img/GitProxy_Architecture.drawio
similarity index 100%
rename from docs/img/GitProxy_Architecture.drawio
rename to website/static/img/GitProxy_Architecture.drawio
diff --git a/docs/img/GitProxy_Architecture.png b/website/static/img/GitProxy_Architecture.png
similarity index 100%
rename from docs/img/GitProxy_Architecture.png
rename to website/static/img/GitProxy_Architecture.png
diff --git a/docs/img/attestation_example.png b/website/static/img/attestation_example.png
similarity index 100%
rename from docs/img/attestation_example.png
rename to website/static/img/attestation_example.png
diff --git a/docs/img/blockForAuth_output.png b/website/static/img/blockForAuth_output.png
similarity index 100%
rename from docs/img/blockForAuth_output.png
rename to website/static/img/blockForAuth_output.png
diff --git a/docs/img/demo.png b/website/static/img/demo.png
similarity index 100%
rename from docs/img/demo.png
rename to website/static/img/demo.png
+
diff --git a/docs/Architecture.md b/website/docs/architecture/architecture.md similarity index 81% rename from docs/Architecture.md rename to website/docs/architecture/architecture.md index 7f49ebe62..e0d27df72 100644 --- a/docs/Architecture.md +++ b/website/docs/architecture/architecture.md @@ -2,7 +2,7 @@ This guide explains GitProxy's various components, and how they communicate with each other when performing a `git push`. -As mentioned in [the README](/README.md), GitProxy is an application that intercepts pushes and applies rules/policies to ensure they're compliant. Although a number of policies are available by default, these can be extended by using plugins. +As mentioned in [the README](https://github.com/finos/git-proxy/blob/main/README.md), GitProxy is an application that intercepts pushes and applies rules/policies to ensure they're compliant. Although a number of policies are available by default, these can be extended by using plugins. ## Overview @@ -10,12 +10,12 @@ GitProxy has several main components: - HTTP Proxy Express app (`/src/proxy`): The actual proxy server for Git. Git operations performed by users are intercepted here, processed by various Express middleware (such as URL rewriting) and applies the relevant **chain** of actions to the payload. Customized functionality in the form of **plugins** are inserted and added to this chain as well. - Chain: A set of **processors** that are applied to an action (i.e. a `git push` operation) before requesting review from a user with permission to approve pushes - - Processor: AKA `Step`. A specific step in the chain where certain rules are applied. See the [list of default processors](./Processors.md) for more details.` - - Plugin: A custom processor that can be added externally to extend GitProxy's default policies. See the [plugin guide](https://git-proxy.finos.org/docs/development/plugins) for more details. + - Processor: AKA `Step`. A specific step in the chain where certain rules are applied. See the [list of default processors](/docs/architecture/processors.md) for more details.` + - Plugin: A custom processor that can be added externally to extend GitProxy's default policies. See the [plugin guide](/docs/development/plugins) for more details. - Backend-for-frontend (BFF) Service API, Express app (`/src/service`): Handles UI requests, user authentication to GitProxy (not to Git), database operations and some of the logic for rejection/approval. Runs by default on port `8080`, and can be configured with the `GIT_PROXY_UI_HOST` and `GIT_PROXY_UI_PORT` environment variables. - Passport: The [library](https://www.passportjs.org/) used to authenticate to the GitProxy API (not the proxy itself - this depends on the Git `user.email`). Supports multiple authentication methods by default ([Local](#local), [AD](#activedirectory), [OIDC](#openid-connect)). - Routes: All the API endpoints used by the UI and proxy to perform operations and fetch or modify GitProxy's state. Except for custom plugin and processor development, there is no need for users or GitProxy administrators to interact with the API directly. -- Configuration (`/src/config`): Loads and validates the configuration from `proxy.config.json`, or any provided config file. Allows customising several aspects of GitProxy, including databases, authentication methods, predefined allowed repositories, commit blocking rules and more. For a full list of configurable parameters, check the [config file schema reference](https://git-proxy.finos.org/docs/configuration/reference/). +- Configuration (`/src/config`): Loads and validates the configuration from `proxy.config.json`, or any provided config file. Allows customising several aspects of GitProxy, including databases, authentication methods, predefined allowed repositories, commit blocking rules and more. For a full list of configurable parameters, check the [config file schema reference](/docs/configuration/reference/). - Web UI, React (`/src/ui`): Allows user-friendly interactions with the application. Shows the list of pushes requiring approval, the list of repositories that users can contribute to, and more. Also allows users to easily review the changes in a push, and approve or reject it manually according to company policy. ## Diagram @@ -24,11 +24,11 @@ These are all the core components in the project, along with some basic user int - + ### Pushing to GitProxy @@ -53,18 +53,18 @@ Don't forget to save and update the attached .drawio (XML)! --> Three types of policies can be applied to incoming pushes: - Default policies: These are already present in the GitProxy pull/push chain and require modifying source code to change their behaviour. - - For example, [`checkUserPushPermission`](./Processors.md#checkuserpushpermission) which simply checks if the pusher's email exists in the GitProxy database, and if their user is marked in the "Contributors" list (`canPush`) for the repository they're trying to push to. + - For example, [`checkUserPushPermission`](/docs/architecture/processors.md#checkuserpushpermission) which simply checks if the pusher's email exists in the GitProxy database, and if their user is marked in the "Contributors" list (`canPush`) for the repository they're trying to push to. - Configurable policies: These are policies that can be easily configured through the GitProxy config (`proxy.config.json` or a custom file). - - For example, [`checkCommitMessages`](./Processors.md#checkcommitmessages) which reads the configuration and matches the string patterns provided with the commit messages in the push in order to block it. + - For example, [`checkCommitMessages`](/docs/architecture/processors.md#checkcommitmessages) which reads the configuration and matches the string patterns provided with the commit messages in the push in order to block it. - Custom policies: - - Plugins: Push/pull plugins provide more flexibility for implementing an organization's rules. For more information, see the [guide on writing your own plugins](https://git-proxy.finos.org/docs/development/plugins). + - Plugins: Push/pull plugins provide more flexibility for implementing an organization's rules. For more information, see the [guide on writing your own plugins](/docs/development/plugins). - Processors: Custom logic may require specific data within a push that isn't available at the end of the chain (where plugins are executed). In this case, the appropriate solution is to write a processor and add it to the correct place in the chain. ## The nitty gritty ### Pre-processors -Pre-processors run before executing the chain. Currently, only executes [`parseAction`](./Processors.md#parseaction), which is in charge of classifying requests as push/pull/default and creating the `Action` object used by the chain. +Pre-processors run before executing the chain. Currently, only executes [`parseAction`](/docs/architecture/processors.md#parseaction), which is in charge of classifying requests as push/pull/default and creating the `Action` object used by the chain. ### Action Chains @@ -74,27 +74,27 @@ Action chains are a list of processors that a Git operation goes through before Executed when a user makes a `git push` to GitProxy. These are the actions in `pushActionChain`, by order of execution: -- [`parsePush`](./Processors.md#parsepush) -- [`checkEmptyBranch`](./Processors.md#checkemptybranch) -- [`checkRepoInAuthorisedList`](./Processors.md#checkrepoinauthorisedlist) -- [`checkCommitMessages`](./Processors.md#checkcommitmessages) -- [`checkAuthorEmails`](./Processors.md#checkauthoremails) -- [`checkUserPushPermission`](./Processors.md#checkuserpushpermission) -- [`pullRemote`](./Processors.md#pullremote) -- [`writePack`](./Processors.md#writepack) -- [`checkHiddenCommits`](./Processors.md#checkhiddencommits) -- [`checkIfWaitingAuth`](./Processors.md#checkifwaitingauth) -- [`preReceive`](./Processors.md#prereceive) -- [`getDiff`](./Processors.md#getdiff) -- [`gitleaks`](./Processors.md#gitleaks) -- [`scanDiff`](./Processors.md#scandiff) -- [`blockForAuth`](./Processors.md#blockforauth) +- [`parsePush`](/docs/architecture/processors.md#parsepush) +- [`checkEmptyBranch`](/docs/architecture/processors.md#checkemptybranch) +- [`checkRepoInAuthorisedList`](/docs/architecture/processors.md#checkrepoinauthorisedlist) +- [`checkCommitMessages`](/docs/architecture/processors.md#checkcommitmessages) +- [`checkAuthorEmails`](/docs/architecture/processors.md#checkauthoremails) +- [`checkUserPushPermission`](/docs/architecture/processors.md#checkuserpushpermission) +- [`pullRemote`](/docs/architecture/processors.md#pullremote) +- [`writePack`](/docs/architecture/processors.md#writepack) +- [`checkHiddenCommits`](/docs/architecture/processors.md#checkhiddencommits) +- [`checkIfWaitingAuth`](/docs/architecture/processors.md#checkifwaitingauth) +- [`preReceive`](/docs/architecture/processors.md#prereceive) +- [`getDiff`](/docs/architecture/processors.md#getdiff) +- [`gitleaks`](/docs/architecture/processors.md#gitleaks) +- [`scanDiff`](/docs/architecture/processors.md#scandiff) +- [`blockForAuth`](/docs/architecture/processors.md#blockforauth) #### Pull action chain Executed when a user makes a `git clone` or `git pull` to GitProxy: -- [`checkRepoInAuthorisedList`](./Processors.md#checkrepoinauthorisedlist) +- [`checkRepoInAuthorisedList`](/docs/architecture/processors.md#checkrepoinauthorisedlist) At present, the pull action chain is only checking that the repository is configured in GitProxy. This ensures it will block pull requests for unknown repositories. @@ -102,17 +102,17 @@ At present, the pull action chain is only checking that the repository is config This chain is executed when making any operation other than a `git push` or `git pull`. -- [`checkRepoInAuthorisedList`](./Processors.md#checkrepoinauthorisedlist) +- [`checkRepoInAuthorisedList`](/docs/architecture/processors.md#checkrepoinauthorisedlist) The default action chain, much like the pull chain, is only checking that the repository is configured in GitProxy. This ensures it will block all git client requests for unknown repositories. ### Post-processors -After processors in the chain are done executing, [`audit`](./Processors.md#audit) is called to store the action along with all of its execution steps in the database for auditing purposes. +After processors in the chain are done executing, [`audit`](/docs/architecture/processors.md#audit) is called to store the action along with all of its execution steps in the database for auditing purposes. -If [`pullRemote`](./Processors.md#pullremote) ran successfully and cloned the repository, then [`clearBareClone`](./Processors.md#clearbareclone) is run to clear up that clone, freeing disk space and ensuring that the _.remote/\*_ folder created does not conflict with any future pushes involving the same SHA. +If [`pullRemote`](/docs/architecture/processors.md#pullremote) ran successfully and cloned the repository, then [`clearBareClone`](/docs/architecture/processors.md#clearbareclone) is run to clear up that clone, freeing disk space and ensuring that the _.remote/\*_ folder created does not conflict with any future pushes involving the same SHA. -Finally, if the action was auto-approved or auto-rejected as a result of running [`preReceive`](./Processors.md#prereceive), it will attempt to auto-approve or auto-reject it. +Finally, if the action was auto-approved or auto-rejected as a result of running [`preReceive`](/docs/architecture/processors.md#prereceive), it will attempt to auto-approve or auto-reject it. ### Authentication @@ -175,7 +175,7 @@ For example: logging in with myusername@mymail.com will create a new user with u New methods can be added by: 1. Extending `/src/service/passport` with the relevant [passport.js strategy](https://www.passportjs.org/packages/). - - The strategy file must have a `configure` method and a `type` string to match with the config method. See the pre-existing methods in [`/src/service/passport`](/src/service/passport) for more details. + - The strategy file must have a `configure` method and a `type` string to match with the config method. See the pre-existing methods in [`/src/service/passport`](https://github.com/finos/git-proxy/blob/main/src/service/passport) for more details. 2. Creating a `proxy.config.json` entry with the required configuration parameters 3. Importing the new strategy and adding it to the `authStrategies` array in `/src/service/passport/index.ts` @@ -224,7 +224,7 @@ Currently supports the following out-of-the-box: #### `commitConfig` -Used in [`checkCommitMessages`](./Processors.md#checkcommitmessages), [`checkAuthorEmails`](./Processors.md#checkauthoremails) and [`scanDiff`](./Processors.md#scandiff) processors to block pushes depending on the given rules. +Used in [`checkCommitMessages`](/docs/architecture/processors.md#checkcommitmessages), [`checkAuthorEmails`](/docs/architecture/processors.md#checkauthoremails) and [`scanDiff`](/docs/architecture/processors.md#scandiff) processors to block pushes depending on the given rules. By default, no rules are applied. @@ -310,13 +310,13 @@ Has a list of `questions`, each of which can be configured with a `label` and a Given the previous configuration, the attestation prompt would look like this: - + #### `domains` Allows setting custom URLs for GitProxy interfaces in case these cannot be determined. -This parameter is used in [`/src/service/urls.ts`](/src/service/urls.ts) to override URLs for the proxy (default: http://localhost:8000) and service (default: http://localhost:8080). +This parameter is used in [`/src/service/urls.ts`](https://github.com/finos/git-proxy/blob/main/src/service/urls.ts) to override URLs for the proxy (default: http://localhost:8000) and service (default: http://localhost:8080). Sample configuration: @@ -356,7 +356,7 @@ Currently unused. Sets the contact email for the Open Source Program Office (or equivalent organisational contact) in the attestation form: - + #### `csrfProtection` @@ -416,7 +416,7 @@ List of database sources. The first source with `enabled` set to `true` will be Each entry has its own unique configuration parameters. -Extending GitProxy to support other databases requires adding the relevant handlers and setup to the [`/src/db`](/src/db/) directory. Feel free to [open an issue](https://github.com/finos/git-proxy/issues) requesting support for any specific databases - or [open a PR](https://github.com/finos/git-proxy/pulls) with the desired changes! +Extending GitProxy to support other databases requires adding the relevant handlers and setup to the [`/src/db`](https://github.com/finos/git-proxy/blob/main/src/db/) directory. Feel free to [open an issue](https://github.com/finos/git-proxy/issues) requesting support for any specific databases - or [open a PR](https://github.com/finos/git-proxy/pulls) with the desired changes! #### `authentication` @@ -432,7 +432,7 @@ Allows defining ways to authenticate to the API. This is useful for securing cus If `apiAuthentication` is left empty, API endpoints will be publicly accesible. -Currently, only JWT auth is supported. This is implemented via the [`jwtAuthHandler` middleware](/src/service/passport/jwtAuthHandler.ts). Aside of validating incoming access tokens, it can also assign roles based on the token payload. +Currently, only JWT auth is supported. This is implemented via the [`jwtAuthHandler` middleware](https://github.com/finos/git-proxy/blob/main/src/service/passport/jwtAuthHandler.ts). Aside of validating incoming access tokens, it can also assign roles based on the token payload. ##### Setting up JWT Authentication diff --git a/docs/Processors.md b/website/docs/architecture/processors.md similarity index 85% rename from docs/Processors.md rename to website/docs/architecture/processors.md index de5bcb696..8f4edc590 100644 --- a/docs/Processors.md +++ b/website/docs/architecture/processors.md @@ -14,7 +14,7 @@ This action also handles fallbacks for v1 legacy proxy URLs. Checks if the URL of the repo being pushed to is present in the GitProxy repo database. If no repo URL in the database matches, the push is blocked. -Source: [/src/proxy/processors/push-action/checkRepoInAuthorisedList.ts](/src/proxy/processors/push-action/checkRepoInAuthorisedList.ts) +Source: [/src/proxy/processors/push-action/checkRepoInAuthorisedList.ts](https://github.com/finos/git-proxy/blob/main/src/proxy/processors/push-action/checkRepoInAuthorisedList.ts) ## `parsePush` @@ -22,13 +22,13 @@ Parses the push request data which comes from the Git client as a buffer that co Also handles extraction of push contents, such as the details of the individual commits contained in the push and the details of `committer` (the user attempting to push the commits through the proxy). -Source: [/src/proxy/processors/push-action/parsePush.ts](/src/proxy/processors/push-action/parsePush.ts) +Source: [/src/proxy/processors/push-action/parsePush.ts](https://github.com/finos/git-proxy/blob/main/src/proxy/processors/push-action/parsePush.ts) ## `checkEmptyBranch` Checks if the push contains any commit data, or is just an empty branch push (pushing a new branch without any additional commits). Empty branch pushes are blocked because subsequent processors require commit data to work correctly. -Source: [/src/proxy/processors/push-action/checkEmptyBranch.ts](/src/proxy/processors/push-action/checkEmptyBranch.ts) +Source: [/src/proxy/processors/push-action/checkEmptyBranch.ts](https://github.com/finos/git-proxy/blob/main/src/proxy/processors/push-action/checkEmptyBranch.ts) ## `checkCommitMessages` @@ -66,7 +66,7 @@ If the arrays are empty, the checks will pass and chain execution will continue. Note that invalid regex patterns will throw an error during proxy startup. These must be fixed in order to initialize GitProxy. -Source: [/src/proxy/processors/push-action/checkCommitMessages.ts](/src/proxy/processors/push-action/checkCommitMessages.ts) +Source: [/src/proxy/processors/push-action/checkCommitMessages.ts](https://github.com/finos/git-proxy/blob/main/src/proxy/processors/push-action/checkCommitMessages.ts) ## `checkAuthorEmails` @@ -76,7 +76,7 @@ If neither of these are configured (set to empty strings), then the checks will Note that invalid regex patterns will throw an error during proxy startup. These must be fixed in order to initialize GitProxy. -Source: [/src/proxy/processors/push-action/checkAuthorEmails.ts](/src/proxy/processors/push-action/checkAuthorEmails.ts) +Source: [/src/proxy/processors/push-action/checkAuthorEmails.ts](https://github.com/finos/git-proxy/blob/main/src/proxy/processors/push-action/checkAuthorEmails.ts) #### `checkUserPushPermission` @@ -90,7 +90,7 @@ This step will fail on various scenarios such as: Note: The _pusher_ can potentially be a different user from the _commit author(s)_. In order to filter the commit authors, you must use the `commitConfig.author` config entry. See [`checkAuthorEmails`](#checkauthoremails) for more details. -Source: [/src/proxy/processors/push-action/checkUserPushPermission.ts](/src/proxy/processors/push-action/checkUserPushPermission.ts) +Source: [/src/proxy/processors/push-action/checkUserPushPermission.ts](https://github.com/finos/git-proxy/blob/main/src/proxy/processors/push-action/checkUserPushPermission.ts) ## `pullRemote` @@ -102,7 +102,7 @@ In the event that the clone fails, pullRemote will automatically delete the _.re If the clone succeeds then the chain will schedule deletion of the clone by [`clearBareClone`](#clearbareclone) after processing of the chain completes. This ensures that disk space used is recovered, subsequent pushes of the same SHA don't conflict and that user credentials cached in the `git clone` are removed. -Source: [/src/proxy/processors/push-action/pullRemote.ts](/src/proxy/processors/push-action/pullRemote.ts) +Source: [/src/proxy/processors/push-action/pullRemote.ts](https://github.com/finos/git-proxy/blob/main/src/proxy/processors/push-action/pullRemote.ts) ## `writePack` @@ -110,7 +110,7 @@ Executes `git receive-pack` with the incoming pack data from the request body in Note that `writePack` sets Git's `receive.unpackLimit` to `0`, which forces Git to always create pack files instead of unpacking objects individually. -Source: [/src/proxy/processors/push-action/writePack.ts](/src/proxy/processors/push-action/writePack.ts) +Source: [/src/proxy/processors/push-action/writePack.ts](https://github.com/finos/git-proxy/blob/main/src/proxy/processors/push-action/writePack.ts) ## `checkHiddenCommits` @@ -118,13 +118,13 @@ Detects "hidden" commits in a push, which is possible if the pack file in the pu It calls `git verify-pack` on each of the new `.idx` files found in [`writePack`](#writepack). If any unreferenced commits are present, the push is blocked. -Source: [/src/proxy/processors/push-action/checkHiddenCommits.ts](/src/proxy/processors/push-action/checkHiddenCommits.ts) +Source: [/src/proxy/processors/push-action/checkHiddenCommits.ts](https://github.com/finos/git-proxy/blob/main/src/proxy/processors/push-action/checkHiddenCommits.ts) ## `checkIfWaitingAuth` Checks if the action has been authorised (approved by a reviewer). If so, allows the push to continue to the remote. It simply continues chain execution if the push hasn't been approved. -Source: [/src/proxy/processors/push-action/checkIfWaitingAuth.ts](/src/proxy/processors/push-action/checkIfWaitingAuth.ts) +Source: [/src/proxy/processors/push-action/checkIfWaitingAuth.ts](https://github.com/finos/git-proxy/blob/main/src/proxy/processors/push-action/checkIfWaitingAuth.ts) ## `preReceive` @@ -142,7 +142,7 @@ This processor will block the push depending on the exit status of the pre-recei For detailed setup instructions and examples, see the [Pre-Receive Hook configuration guide](https://git-proxy.finos.org/docs/configuration/pre-receive/). -Source: [/src/proxy/processors/push-action/preReceive.ts](/src/proxy/processors/push-action/preReceive.ts) +Source: [/src/proxy/processors/push-action/preReceive.ts](https://github.com/finos/git-proxy/blob/main/src/proxy/processors/push-action/preReceive.ts) ## `getDiff` @@ -150,7 +150,7 @@ Executes `git diff` to obtain the diff for the given revision range. If there ar The data extracted in this step is later used in [`scanDiff`](#scandiff). -Source: [/src/proxy/processors/push-action/getDiff.ts](/src/proxy/processors/push-action/getDiff.ts) +Source: [/src/proxy/processors/push-action/getDiff.ts](https://github.com/finos/git-proxy/blob/main/src/proxy/processors/push-action/getDiff.ts) ## `gitleaks` @@ -165,7 +165,7 @@ The following parameters can be configured: This processor runs the Gitleaks check starting from the root commit to the `commitFrom` value present in the push. If the Gitleaks check fails (nonzero exit code), or otherwise cannot spawn, the push will be blocked. -Source: [/src/proxy/processors/push-action/gitleaks.ts](/src/proxy/processors/push-action/gitleaks.ts) +Source: [/src/proxy/processors/push-action/gitleaks.ts](https://github.com/finos/git-proxy/blob/main/src/proxy/processors/push-action/gitleaks.ts) ## `scanDiff` @@ -203,7 +203,7 @@ This will scan every file changed and try to match the configured literals, patt Note that invalid regex patterns will throw an error during proxy startup. These must be fixed in order to initialize GitProxy. -Source: [/src/proxy/processors/push-action/scanDiff.ts](/src/proxy/processors/push-action/scanDiff.ts) +Source: [/src/proxy/processors/push-action/scanDiff.ts](https://github.com/finos/git-proxy/blob/main/src/proxy/processors/push-action/scanDiff.ts) ## `blockForAuth` @@ -211,9 +211,9 @@ This action appends a message to be displayed after all the processors have fini Note that this message will show again even if the push had been previously rejected by a reviewer or cancelled and resubmitted by the committer. After a manual rejection, pushing again creates a new `action` object so that the push can be re-reviewed and approved. - + -Source: [/src/proxy/processors/push-action/blockForAuth.ts](/src/proxy/processors/push-action/blockForAuth.ts) +Source: [/src/proxy/processors/push-action/blockForAuth.ts](https://github.com/finos/git-proxy/blob/main/src/proxy/processors/push-action/blockForAuth.ts) ## `audit` @@ -284,4 +284,4 @@ Recursively removes the contents of the (modified) repository clone stored in `. `clearBareClone` runs only if `pullRemote` was successful. -Source: [/src/proxy/processors/post-processor/clearBareClone.ts](/src/proxy/processors/post-processor/clearBareClone.ts) +Source: [/src/proxy/processors/post-processor/clearBareClone.ts](https://github.com/finos/git-proxy/blob/main/src/proxy/processors/post-processor/clearBareClone.ts) diff --git a/website/docs/deployment.mdx b/website/docs/deployment.mdx index 70479a901..bfc5a549f 100644 --- a/website/docs/deployment.mdx +++ b/website/docs/deployment.mdx @@ -126,7 +126,7 @@ remote: http://localhost:8080/dashboard/push/000000__b12557 - Username: `admin` - Password: `admin` - See the [Authentication](https://github.com/finos/git-proxy/blob/main/docs/Architecture.md#authentication) section of the architecture guide for more details. + See the [Authentication](/docs/architecture/architecture.md#authentication) section of the architecture guide for more details. 3. Review the push and approve it 4. Push again to forward to upstream: ```bash diff --git a/docs/Upgrading to v2.md b/website/docs/upgrading-to-v2.md similarity index 97% rename from docs/Upgrading to v2.md rename to website/docs/upgrading-to-v2.md index 1443eae10..fc94dcee5 100644 --- a/docs/Upgrading to v2.md +++ b/website/docs/upgrading-to-v2.md @@ -10,7 +10,7 @@ Two important breaking changes were made: ### Associate commits by email -Commits are no longer associated by Git's `user.name`. Now, they're associated by email (to match the handling of commits by GitHub, GitLab and other SCM providers), which allows Git Proxy to handle multiple SCM providers. [#973](github.com/finos/git-proxy/pull/973) +Commits are no longer associated by Git's `user.name`. Now, they're associated by email (to match the handling of commits by GitHub, GitLab and other SCM providers), which allows Git Proxy to handle multiple SCM providers. [#973](https://github.com/finos/git-proxy/pull/973) In practice, pushes that were working in v1 (made with an improperly configured git client) may be blocked in v2 due to the change in requirements. The user's GitProxy email must match the commit's email (Git's `user.email`). This is often already required by a firm's contribution policy or to pass a CLA (Contributor License Agreement) check on a project. @@ -30,7 +30,7 @@ If you encounter any errors not on this guide, feel free to [open a discussion]( ### Errors when pushing to a repo that was working in v1: -#### fatal: