docs: architecture guide #1391

jescalada · 2026-02-07T04:43:50Z

Closes #1325. Previous PR (#1335) got stuck because of a GitHub bug where comments on orphaned commits cannot be closed.

Previous PR description:

The architecture diagram can be edited from this file on diagrams.net
GitProxy_Architecture.drawio

To-do

Add section for authentication methods

Add section for databases

Add plugin guide

Add deployment guide - to be added later by @tabathad

Fix all the to-dos

…nos/git-proxy into 1325-architecture-guide-draft

Co-authored-by: Fabio Vincenzi <93596376+fabiovincenzi@users.noreply.github.com> Signed-off-by: Juan Escalada <97265671+jescalada@users.noreply.github.com>

…chain execution

…ove todos

Co-authored-by: Fabio Vincenzi <93596376+fabiovincenzi@users.noreply.github.com> Signed-off-by: Juan Escalada <97265671+jescalada@users.noreply.github.com>

Co-authored-by: Kris West <kristopher.west@natwest.com> Signed-off-by: Juan Escalada <97265671+jescalada@users.noreply.github.com>

…nos/git-proxy into 1325-architecture-guide-draft

github-actions · 2026-02-07T04:44:08Z

Dependency Review

✅ No vulnerabilities or license issues or OpenSSF Scorecard issues found.

Scanned Files

None

netlify · 2026-02-07T04:44:51Z

✅ Deploy Preview for endearing-brigadeiros-63f9d0 canceled.

Name	Link
🔨 Latest commit	`734a7a5`
🔍 Latest deploy log	https://app.netlify.com/projects/endearing-brigadeiros-63f9d0/deploys/698a00f437e8530008e644ce

codecov · 2026-02-09T13:01:06Z

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 81.34%. Comparing base (6fb63d0) to head (734a7a5).

Additional details and impacted files

@@           Coverage Diff           @@
##             main    #1391   +/-   ##
=======================================
  Coverage   81.34%   81.34%           
=======================================
  Files          65       65           
  Lines        4648     4648           
  Branches      792      792           
=======================================
  Hits         3781     3781           
  Misses        852      852           
  Partials       15       15

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

kriswest

Added some corrections, questions and updates for open PRs expected to be merged shortly for the v2 release.

kriswest · 2026-02-09T14:42:16Z

docs/Architecture.md

+- [`preReceive`](#prereceive)
+- [`getDiff`](#getdiff)
+- [`gitleaks`](#gitleaks)
+- [`clearBareClone`](#clearbareclone)


Suggested change

- [`clearBareClone`](#clearbareclone)

Removing this from the chain in #1393 and conditionally triggering it based on whether pullRemote succeeded

kriswest · 2026-02-09T14:45:43Z

docs/Architecture.md

+After processors in the chain are done executing, [`audit`](#audit) is called to store the action along with all of its execution steps in the database for auditing purposes.
+
+Then, if the action was auto-approved or auto-rejected as a result of running [`preReceive`](#prereceive), it will attempt to auto-approve or auto-reject it.


Suggested change

After processors in the chain are done executing, [`audit`](#audit) is called to store the action along with all of its execution steps in the database for auditing purposes.

Then, if the action was auto-approved or auto-rejected as a result of running [`preReceive`](#prereceive), it will attempt to auto-approve or auto-reject it.

After processors in the chain are done executing, [`audit`](#audit) is called to store the action along with all of its execution steps in the database for auditing purposes.

If [`pullRemote`](#pullremote) ran successfully and cloned the repository, then [`clearBareClone`](#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`](#prereceive), it will attempt to auto-approve or auto-reject it.

kriswest · 2026-02-09T14:49:33Z

docs/Architecture.md

+
+Action chains are a list of processors that a Git operation goes through before awaiting approval. Three action chains are currently available:
+
+#### Push action chain


the pre-processer parseAction doesn't get a mention. I think some content on it is necessary, particularly as it classifies requests (push/pull/default) and hence control what subsequent steps run.

#1393 also pulls out audit and clearBareClone into a post-processors folder as they don't quite fit as pure push processors (audit is now applied to everything, clearBareClone isn't part of the chain now but conditionally invoked by it if pullRemote was)

kriswest · 2026-02-09T14:50:45Z

docs/Architecture.md

+
+Executed when a user makes a `git clone` or `git pull` to GitProxy:
+
+- [`checkRepoInAuthorisedList`](#checkrepoinauthorisedlist)


Suggested change

- [`checkRepoInAuthorisedList`](#checkrepoinauthorisedlist)

- [`checkRepoInAuthorisedList`](#checkrepoinauthorisedlist)

-

At present the pull action chain is only checking that the repository is configured in Git Proxy, ensuring that it will block pull requests for unknown repositories.

kriswest · 2026-02-09T14:51:19Z

docs/Architecture.md

+
+This chain is executed when making any operation other than a `git push` or `git pull`.
+
+- [`checkRepoInAuthorisedList`](#checkrepoinauthorisedlist)


Suggested change

- [`checkRepoInAuthorisedList`](#checkrepoinauthorisedlist)

- [`checkRepoInAuthorisedList`](#checkrepoinauthorisedlist)

-

At present the default action chain is only checking that the repository is configured in Git Proxy, ensuring that it will block all git client requests for unknown repositories.

kriswest · 2026-02-09T15:32:57Z

docs/Architecture.md

+
+#### `contactEmail`
+
+Sets the contact email for the Open Source Program Office in the attestation form:


Suggested change

Sets the contact email for the Open Source Program Office in the attestation form:

Sets the contact email for the Open Source Program Office (or equivalent organisational contact) in the attestation form:

kriswest · 2026-02-09T15:33:55Z

docs/Architecture.md

+
+#### `authorisedList`
+
+Defines a list of repositories that are allowed to be pushed to through the proxy. Note that **repositories can also be added through the UI or manually editing the database**.


Suggested change

Defines a list of repositories that are allowed to be pushed to through the proxy. Note that **repositories can also be added through the UI or manually editing the database**.

Defines a initial list of repositories that are allowed to be pushed to through the proxy. Note that **repositories can also be added through the UI, API or by manually editing the database**.

kriswest · 2026-02-09T15:35:07Z

docs/Architecture.md

+
+##### Setting up JWT Authentication
+
+When JWT authentication is enabled, all incoming requests must provide a valid JWT access token in the UI. This can be set in the settings tab.


Clarify what type of request - presumably the API (rather than the git proxy interface)

kriswest · 2026-02-09T15:35:19Z

docs/Architecture.md

+
+When JWT authentication is enabled, all incoming requests must provide a valid JWT access token in the UI. This can be set in the settings tab.
+
+If no token, or an invalid/expired token is set, requests will fail with a `401` Unauthorized response.


Suggested change

If no token, or an invalid/expired token is set, requests will fail with a `401` Unauthorized response.

If no token, or an invalid/expired token is sent, requests will fail with a `401` Unauthorized response.

kriswest · 2026-02-09T15:36:37Z

docs/Architecture.md

+
+#### `tls`
+
+Allows configuring TLS (Transport Layer Security) **for the proxy** (not for the API):


Suggested change

Allows configuring TLS (Transport Layer Security) **for the proxy** (not for the API):

Allows configuring TLS (Transport Layer Security) **for the proxy** (rather than for the API or UI):

A pointer on how to configure for the API & UI would be useful

coopernetes · 2026-02-09T17:35:58Z

docs/Architecture.md

+  - 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).
+  - 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


This is just a nit but are each individual proxying/filtering logical steps worth documenting as part of the app's architecture? This seems most appropriate for some sort of reference doc (configuration, app, proxying steps, etc).

It distracts from the actual app behaviour which the rest of the doc explains pretty well.

Maybe just a quick reference diagram of the various steps showing the action pipeline?

coopernetes · 2026-02-09T17:39:00Z

docs/Architecture.md

+
+GitProxy has several main components:
+
+- 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` or `8443` if TLS is enabled. These can be changed through the `GIT_PROXY_SERVER_PORT` and `GIT_PROXY_HTTPS_SERVER_PORT` environment variables.


Suggested change

- 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` or `8443` if TLS is enabled. These can be changed through the `GIT_PROXY_SERVER_PORT` and `GIT_PROXY_HTTPS_SERVER_PORT` environment variables.

- 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.

Runs by default on port 8000 or 8443 if TLS is enabled. These can be changed through the GIT_PROXY_SERVER_PORT and GIT_PROXY_HTTPS_SERVER_PORT environment variables.

Probably better documented in a configuration reference + deployment guide.

coopernetes · 2026-02-09T17:39:29Z

docs/Architecture.md

+  - 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](https://git-proxy.finos.org/docs/development/plugins) for more details.
+- 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`, and can be configured with the `GIT_PROXY_UI_HOST` and `GIT_PROXY_UI_PORT` environment variables.


Suggested change

- 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`, and can be configured with the `GIT_PROXY_UI_HOST` and `GIT_PROXY_UI_PORT` environment variables.

- 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.

coopernetes · 2026-02-09T17:40:02Z

docs/Architecture.md

+  - 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/).
+- UI (`/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.


Suggested change

- UI (`/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.

- 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.

coopernetes · 2026-02-09T17:40:41Z

docs/img/GitProxy_Architecture.png

Diagram looks great, the component view and interactions are very useful!

jescalada and others added 30 commits December 27, 2025 16:03

docs: add basic overview of app architecture

66361d4

docs: extend app architecture overview

e514aeb

docs: add architecture diagram

4e853c2

docs: add basic flows and policy definition

b9a69d4

docs: add descriptions for all push/pull actions

b45d091

Merge branch 'main' into 1325-architecture-guide-draft

dd1796f

docs: add authentication section

95e4eca

docs: add entries for config parameters and customization

e3ea864

Merge branch 'main' into 1325-architecture-guide-draft

6dc9345

docs: add remaining config entries

57ebd03

docs: improve wording, fix typos, add missing links

3e2ca56

Merge branch '1325-architecture-guide-draft' of https://github.com/fi…

cb96240

…nos/git-proxy into 1325-architecture-guide-draft

docs: add screenshots and missing links, remove todos

ce66b6e

Update docs/Architecture.md

e2ad052

Co-authored-by: Fabio Vincenzi <93596376+fabiovincenzi@users.noreply.github.com> Signed-off-by: Juan Escalada <97265671+jescalada@users.noreply.github.com>

Update docs/Architecture.md

5ee2aef

Co-authored-by: Fabio Vincenzi <93596376+fabiovincenzi@users.noreply.github.com> Signed-off-by: Juan Escalada <97265671+jescalada@users.noreply.github.com>

Update docs/Architecture.md

d3e6650

Co-authored-by: Fabio Vincenzi <93596376+fabiovincenzi@users.noreply.github.com> Signed-off-by: Juan Escalada <97265671+jescalada@users.noreply.github.com>

Update docs/Architecture.md

cd16b78

Co-authored-by: Fabio Vincenzi <93596376+fabiovincenzi@users.noreply.github.com> Signed-off-by: Juan Escalada <97265671+jescalada@users.noreply.github.com>

Update docs/Architecture.md

754f5ec

Co-authored-by: Fabio Vincenzi <93596376+fabiovincenzi@users.noreply.github.com> Signed-off-by: Juan Escalada <97265671+jescalada@users.noreply.github.com>

Update docs/Architecture.md

3975018

Co-authored-by: Fabio Vincenzi <93596376+fabiovincenzi@users.noreply.github.com> Signed-off-by: Juan Escalada <97265671+jescalada@users.noreply.github.com>

Update docs/Architecture.md

c852875

Co-authored-by: Fabio Vincenzi <93596376+fabiovincenzi@users.noreply.github.com> Signed-off-by: Juan Escalada <97265671+jescalada@users.noreply.github.com>

docs: document missing audit processor and prereceive handling after …

c6da24b

…chain execution

docs: improve clearBareClone explanation, add plugin guide links, rem…

7fd31db

…ove todos

docs: update architecture diagram and set bg to white

5bf8f51

docs: add JWT api authentication guide

4ea9433

Merge branch 'main' into 1325-architecture-guide-draft

12e374a

Merge branch 'main' into 1325-architecture-guide-draft

783a262

Merge branch 'main' into 1325-architecture-guide-draft

6e2c8be

Update docs/Architecture.md

378c7f2

Co-authored-by: Fabio Vincenzi <93596376+fabiovincenzi@users.noreply.github.com> Signed-off-by: Juan Escalada <97265671+jescalada@users.noreply.github.com>

Update docs/Architecture.md

562c3b1

Co-authored-by: Kris West <kristopher.west@natwest.com> Signed-off-by: Juan Escalada <97265671+jescalada@users.noreply.github.com>

docs: proxy env variables configuration, add suggestions section

7fa4b29

jescalada and others added 6 commits February 4, 2026 12:49

Merge branch 'main' into 1325-architecture-guide-draft

925a183

chore: fix invalid JSON and todo

faa0dc2

Merge branch '1325-architecture-guide-draft' of https://github.com/fi…

debe57e

…nos/git-proxy into 1325-architecture-guide-draft

Merge branch 'main' into 1325-architecture-guide-draft

707b3b8

Merge branch 'main' into 1325-architecture-guide-draft

2345366

Merge branch 'main' into 1325-architecture-guide-draft

1e98d9d

github-actions bot added the documentation Improvements or additions to documentation label Feb 7, 2026

This was referenced Feb 7, 2026

Roadmap to v2.0 release #1368

Open

docs: architecture guide #1335

Closed

jescalada requested a review from kriswest February 7, 2026 06:21

kriswest requested a review from a team February 9, 2026 09:41

jescalada mentioned this pull request Feb 9, 2026

fix: improve handling of repository clones in the .remote folder #1393

Open

Merge branch 'main' into 1325-architecture-guide-draft

debd9b9

kriswest requested changes Feb 9, 2026

View reviewed changes

Merge branch 'main' into 1325-architecture-guide-draft

734a7a5

coopernetes reviewed Feb 9, 2026

View reviewed changes

coopernetes mentioned this pull request Feb 9, 2026

docs: restructure contributing docs and improve E2E test infrastructure #1398

Open

		After processors in the chain are done executing, [`audit`](#audit) is called to store the action along with all of its execution steps in the database for auditing purposes.

		Then, if the action was auto-approved or auto-rejected as a result of running [`preReceive`](#prereceive), it will attempt to auto-approve or auto-reject it.


		Action chains are a list of processors that a Git operation goes through before awaiting approval. Three action chains are currently available:

		#### Push action chain


		Executed when a user makes a `git clone` or `git pull` to GitProxy:

		- [`checkRepoInAuthorisedList`](#checkrepoinauthorisedlist)


		This chain is executed when making any operation other than a `git push` or `git pull`.

		- [`checkRepoInAuthorisedList`](#checkrepoinauthorisedlist)


		#### `contactEmail`

		Sets the contact email for the Open Source Program Office in the attestation form:


		#### `authorisedList`

		Defines a list of repositories that are allowed to be pushed to through the proxy. Note that repositories can also be added through the UI or manually editing the database.

	Defines a list of repositories that are allowed to be pushed to through the proxy. Note that repositories can also be added through the UI or manually editing the database.
	Defines a initial list of repositories that are allowed to be pushed to through the proxy. Note that repositories can also be added through the UI, API or by manually editing the database.


		##### Setting up JWT Authentication

		When JWT authentication is enabled, all incoming requests must provide a valid JWT access token in the UI. This can be set in the settings tab.


		When JWT authentication is enabled, all incoming requests must provide a valid JWT access token in the UI. This can be set in the settings tab.

		If no token, or an invalid/expired token is set, requests will fail with a `401` Unauthorized response.


		#### `tls`

		Allows configuring TLS (Transport Layer Security) for the proxy (not for the API):


		GitProxy has several main components:

		- 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` or `8443` if TLS is enabled. These can be changed through the `GIT_PROXY_SERVER_PORT` and `GIT_PROXY_HTTPS_SERVER_PORT` environment variables.

	- 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` or `8443` if TLS is enabled. These can be changed through the `GIT_PROXY_SERVER_PORT` and `GIT_PROXY_HTTPS_SERVER_PORT` environment variables.
	- 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.

	- 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`, and can be configured with the `GIT_PROXY_UI_HOST` and `GIT_PROXY_UI_PORT` environment variables.
	- 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.

	- UI (`/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.
	- 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.

docs: architecture guide #1391

Are you sure you want to change the base?

docs: architecture guide #1391

Conversation

jescalada commented Feb 7, 2026

To-do

Uh oh!

github-actions bot commented Feb 7, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Dependency Review

Scanned Files

Uh oh!

netlify bot commented Feb 7, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

✅ Deploy Preview for endearing-brigadeiros-63f9d0 canceled.

Uh oh!

codecov bot commented Feb 9, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

kriswest left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

github-actions bot commented Feb 7, 2026 •

edited

Loading

netlify bot commented Feb 7, 2026 •

edited

Loading

codecov bot commented Feb 9, 2026 •

edited

Loading