docs: architecture guide

[jescalada]

Closes #1325.

Feel free to add anything that's missing! Let me know if you'd like me to split a section into its own page.

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
• Fix all the to-dos

[netlify]

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

Name	Link
🔨 Latest commit	6239643
🔍 Latest deploy log	https://app.netlify.com/projects/endearing-brigadeiros-63f9d0/deploys/696b338a9109dd0008775a34

[github-actions]

Dependency Review

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

Scanned Files

None

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 80.40%. Comparing base (ecd6161) to head (4ea9433).
⚠️ Report is 5 commits behind head on main.

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

[fabiovincenzi]

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.

[jescalada]

Do we let the end user know if their push is ready to push again in this case? I thought the push would go through the processors and then automatically get pushed to the remote in one go. 🤔

Just want to make sure that there's a clear message displayed so that users don't "wait" for approval when there's no need!

[grovesy]

@jescalada The original design was the user had to 'repush'' if the push was blocked for any manually steps. The reason for this - was didn't want to store any sensitive credential data in GP itself. Once approved the user receives an email or other notification that they can re-push.

If the initial push is fully auto-approved all the way through (i.e. all checks were automated), then the push should just carry on through and the users receives the usual git response that their push was good - i.e. no notification that ''you can push'' would be required (as, the user is 'done')

If someone can verify that is the current implementation, as I get my head back into the project.

-Paul

[fabiovincenzi]

@grovesy @jescalada

The flow remains exactly the same - users always need to re-push.

The pre-receive hook simply automates what a human would do manually: clicking "Approve" or "Reject" in the UI.

• Exit 0 → Equivalent to clicking "Approve"
• Exit 1 → Equivalent to clicking "Reject"
• Exit 2 → Requires manual approval

From the user's perspective, nothing changes:

1. First push → "GitProxy has received your push" + link
2. Re-push required (immediate if auto-approved, or wait for manual approval)

The only difference is who approves: the hook script or a human.