docs: architecture guide #1335
Open
docs: architecture guide #1335
+717
−0
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
✅ Deploy Preview for endearing-brigadeiros-63f9d0 canceled.
|
Dependency Review✅ No vulnerabilities or license issues or OpenSSF Scorecard issues found.Scanned FilesNone |
github-actions
bot
added
the
documentation
Codecov Report✅ All modified and coverable lines are covered by tests. Additional details and impacted files@@ Coverage Diff @@
## main #1335 +/- ##
=======================================
Coverage 80.40% 80.40%
=======================================
Files 65 65
Lines 4608 4608
Branches 776 776
=======================================
Hits 3705 3705
Misses 888 888
Partials 15 15 ☔ View full report in Codecov by Sentry. 🚀 New features to boost your workflow:
|
…nos/git-proxy into 1325-architecture-guide-draft
| - [`clearBareClone`](#clearbareclone) | ||
| - [`scanDiff`](#scandiff) | ||
| - [`blockForAuth`](#blockforauth) | ||
|
|
Contributor
There was a problem hiding this comment.
Maybe document here the audit processor that runs in the finally block (see chain.ts:54) after all chain processors complete.
| <!-- Todo: Add link to plugin guide --> | ||
| - Service/API (`/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`. | ||
| - 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. |
Contributor
There was a problem hiding this comment.
Do we want to document somewere all the APIs? maybe mention it here and have a mdx to show on the website?
| - Proxy (`/src/proxy`): The actual proxy for Git. Git operations performed by users are intercepted here to apply the relevant **chain**. Also loads **plugins** and adds them to the chain. Runs by default on port `8000`. | ||
| - 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) below for more details.` | ||
| - Plugin: A custom processor that can be added externally to extend GitProxy's default policies. See the plugin guide for more details. |
Contributor
There was a problem hiding this comment.
Suggested change
| - Plugin: A custom processor that can be added externally to extend GitProxy's default policies. See the plugin guide 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. |
|
|
||
| #### `preReceive` | ||
|
|
||
| Allows executing pre-receive hooks from `.sh` scripts located in the `./hooks` directory. **Also allows bypassing the manual approval process.** This enables admins to reuse GitHub enterprise commit policies and provide a seamless experience for contributors who no longer need to wait for approval or be aware of GitProxy intercepting their pushes. |
Contributor
There was a problem hiding this comment.
Suggested change
| Allows executing pre-receive hooks from `.sh` scripts located in the `./hooks` directory. **Also allows bypassing the manual approval process.** This enables admins to reuse GitHub enterprise commit policies and provide a seamless experience for contributors who no longer need to wait for approval or be aware of GitProxy intercepting their pushes. | |
| Allows executing pre-receive hooks from `.sh` scripts located in the `./hooks` directory. **Also allows automating the approval process.** This enables admins to reuse GitHub enterprise commit policies and provide a seamless experience for contributors who no longer need to wait for manual approval or be aware of GitProxy intercepting their pushes. |
|
|
||
| Allows executing pre-receive hooks from `.sh` scripts located in the `./hooks` directory. **Also allows bypassing the manual approval process.** This enables admins to reuse GitHub enterprise commit policies and provide a seamless experience for contributors who no longer need to wait for approval or be aware of GitProxy intercepting their pushes. | ||
|
|
||
| Pre-receive hooks are a feature that allows blocking unwanted commits based on rules described in `.sh` scripts. GitHub provides a set of [sample rules](https://github.com/github/platform-samples/blob/master/pre-receive-hooks) to get started. |
Contributor
There was a problem hiding this comment.
Suggested change
| Pre-receive hooks are a feature that allows blocking unwanted commits based on rules described in `.sh` scripts. GitHub provides a set of [sample rules](https://github.com/github/platform-samples/blob/master/pre-receive-hooks) to get started. | |
| Pre-receive hooks are a feature that allows blocking or automatically approving commits based on rules described in `.sh` scripts. GitHub provides a set of [sample rules](https://github.com/github/platform-samples/blob/master/pre-receive-hooks) to get started. |
| Allows executing pre-receive hooks from `.sh` scripts located in the `./hooks` directory. **Also allows bypassing the manual approval process.** This enables admins to reuse GitHub enterprise commit policies and provide a seamless experience for contributors who no longer need to wait for approval or be aware of GitProxy intercepting their pushes. | ||
|
|
||
| Pre-receive hooks are a feature that allows blocking unwanted commits based on rules described in `.sh` scripts. GitHub provides a set of [sample rules](https://github.com/github/platform-samples/blob/master/pre-receive-hooks) to get started. | ||
|
|
Contributor
There was a problem hiding this comment.
Suggested change
| **Important**: The pre-receive hook does not bypass the other processors in the chain. All processors continue to execute normally, and any of them can still block the push. The pre-receive hook only determines whether the push will be auto-approved, auto-rejected, or require manual review after all processors have completed. |
|
|
||
| This processor will block the push depending on the exit status of the pre-receive hook: | ||
|
|
||
| - Exit status `0`: Sets the push to `autoApproved`, skipping the requirement for subsequent approval. Note that this doesn't affect the other processors, which may still block the push. |
Contributor
There was a problem hiding this comment.
Suggested change
| - Exit status `0`: Sets the push to `autoApproved`, skipping the requirement for subsequent approval. Note that this doesn't affect the other processors, which may still block the push. | |
| - Exit status `0`: Sets the push to `autoApproved`. If no other processors block the push, the contributor can immediately push again to the upstream repository without waiting for manual approval. |
| This processor will block the push depending on the exit status of the pre-receive hook: | ||
|
|
||
| - Exit status `0`: Sets the push to `autoApproved`, skipping the requirement for subsequent approval. Note that this doesn't affect the other processors, which may still block the push. | ||
| <!-- Todo: confirm whether pushes that passed the prereceive can still be blocked --> |
Contributor
There was a problem hiding this comment.
Suggested change
| <!-- Todo: confirm whether pushes that passed the prereceive can still be blocked --> |
| - Exit status `0`: Sets the push to `autoApproved`, skipping the requirement for subsequent approval. Note that this doesn't affect the other processors, which may still block the push. | ||
| <!-- Todo: confirm whether pushes that passed the prereceive can still be blocked --> | ||
| - Exit status `1`: Sets the push to `autoRejected`, automatically rejecting the push regardless of whether the other processors succeed. | ||
| - Exit status `2`: Requires subsequent approval as any regular push. |
Contributor
There was a problem hiding this comment.
Suggested change
| - Exit status `2`: Requires subsequent approval as any regular push. | |
| - Exit status `2`: Requires subsequent manual approval as any regular push, even if all processors succeed. | |
| For detailed setup instructions and examples, see the [Pre-Receive Hook configuration guide](https://git-proxy.finos.org/docs/configuration/pre-receive/). |
|
|
||
| - Exit status `0`: Sets the push to `autoApproved`, skipping the requirement for subsequent approval. Note that this doesn't affect the other processors, which may still block the push. | ||
| <!-- Todo: confirm whether pushes that passed the prereceive can still be blocked --> | ||
| - Exit status `1`: Sets the push to `autoRejected`, automatically rejecting the push regardless of whether the other processors succeed. |
Contributor
There was a problem hiding this comment.
Suggested change
| - Exit status `1`: Sets the push to `autoRejected`, automatically rejecting the push regardless of whether the other processors succeed. | |
| - Exit status `1`: Sets the push to `autoRejected`, automatically rejecting the push after the chain completes, regardless of whether the other processors would have allowed it. |
15 tasks
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Closes #1325.
Note: So far, this covers part of the architecture guide. Would love some help on improving/scoping this guide!
The architecture diagram can be edited from this file on diagrams.net
GitProxy architecture(3).drawio
To-do