Skip to content

Commit fd2d7f7

Browse files
committed
Merge remote-tracking branch 'upstream/main' into fix/schema-driven-deprecation-warnings
2 parents 14c7270 + c4e2107 commit fd2d7f7

52 files changed

Lines changed: 411 additions & 265 deletions

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎.github/PULL_REQUEST_TEMPLATE.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -53,7 +53,7 @@ Resolves #
5353
Tests are required for new functionality (80%+ patch coverage enforced by CodeCov).
5454
Add tests in the appropriate location:
5555
- test/ — Unit and integration tests (Vitest). Organised by module (processors/, db/, services/, plugin/, etc.)
56-
- tests/e2e/ — End-to-end tests (Vitest + Docker). Real git operations against a containerised environment.
56+
- test/e2e/ — End-to-end tests (Vitest + Docker). Real git operations against a containerised environment.
5757
- cypress/e2e/ — UI tests (Cypress). Dashboard UI end-to-end tests.
5858
-->
5959

‎.github/dependabot.yml‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -22,7 +22,7 @@ updates:
2222
- package-ecosystem: docker
2323
directories:
2424
- '/'
25-
- '/localgit'
25+
- '/test/e2e/localgit'
2626
schedule:
2727
interval: weekly
2828
cooldown:

.grype.yaml renamed to .github/security/grype.yaml

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
fail-on-severity: high
22
sort-by: severity
3-
output-template-file: .grype-report.tmpl
3+
output-template-file: .github/security/grype-report.tmpl
44

55
ignore:
66
- fix-state: 'wont-fix'

‎.github/workflows/cve.yml‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -36,14 +36,14 @@ jobs:
3636
- name: Scan (table)
3737
run: |
3838
${{ steps.grype.outputs.cmd }} dir:. \
39-
--config .grype.yaml \
39+
--config .github/security/grype.yaml \
4040
--output template
4141
4242
- name: Scan (SARIF)
4343
if: ${{ always() }}
4444
run: |
4545
${{ steps.grype.outputs.cmd }} dir:. \
46-
--config .grype.yaml \
46+
--config .github/security/grype.yaml \
4747
--output sarif --file grype-results.sarif || true
4848
4949
- name: Upload SARIF report

‎.github/workflows/e2e.yml‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -19,6 +19,7 @@ jobs:
1919
suite: [vitest, cypress]
2020
env:
2121
BUILDX_CACHE_SCOPE: ${{ matrix.suite }}-build
22+
COMPOSE_FILE: test/e2e/docker-compose.yml:test/e2e/docker-compose.ci.yml
2223

2324
steps:
2425
- name: Harden the runner (Audit all outbound calls)
@@ -56,7 +57,7 @@ jobs:
5657
git config --global init.defaultBranch main
5758
5859
- name: Build and start services with Docker Compose
59-
run: docker compose -f docker-compose.yml -f docker-compose.ci.yml up -d --build --wait
60+
run: docker compose up -d --build --wait
6061

6162
- name: Debug service state
6263
if: failure()

‎.gitignore‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -278,6 +278,9 @@ website/.docusaurus
278278
test/keys/
279279
test/.ssh/
280280

281+
# Generated local TLS certificates (see scripts/create-cert.sh)
282+
certs/*.pem
283+
281284
# VS COde IDE
282285
.vscode/settings.json
283286

‎CHARTER.md‎

Lines changed: 45 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,45 @@
1+
# GitProxy Technical Charter
2+
3+
## Mission
4+
5+
GitProxy enables organisations — particularly regulated financial institutions and other enterprises — to enforce configurable policies on outgoing Git push operations, ensuring compliance with security, legal, and risk requirements while preserving the standard open source developer experience.
6+
7+
## Scope
8+
9+
The project develops and maintains:
10+
11+
- The Git HTTP and SSH proxy server
12+
- The policy engine (processor chain and plugin system)
13+
- The approval and review workflow
14+
- The service API and web-based dashboard
15+
- The command-line interface (CLI)
16+
- Associated documentation and tooling
17+
18+
Out of scope:
19+
20+
- Organisation-specific policy content or plugin implementations
21+
- Operational support for production deployments
22+
23+
## Maintainer Structure
24+
25+
The project community consists of Contributors and Maintainers:
26+
27+
- **Contributor** — anyone who submits a contribution to the project (code, issues, comments, documentation, media, or any combination).
28+
- **Maintainer** — a Contributor who, by virtue of their contribution history, has been given write access to project repositories and may merge approved contributions.
29+
- **Lead Maintainer** — the project's interface with the FINOS team and Board. Responsible for approving quarterly project reports and communicating on behalf of the project. Elected by a vote of the Maintainers.
30+
31+
The Maintainers collectively serve as the project's technical steering body. The current roster is recorded in [`MAINTAINERS.md`](MAINTAINERS.md).
32+
33+
## Decision Making
34+
35+
Maintainers reach decisions by consensus where possible, and by vote when necessary. The voting process, contribution rules, cross-firm review requirements, and dispute resolution procedures are defined in [`CONTRIBUTING.md`](CONTRIBUTING.md).
36+
37+
## Intellectual Property
38+
39+
- The project is licensed under the [Apache License, Version 2.0](LICENSE).
40+
- Contributions are governed by the [FINOS IP Policy](https://community.finos.org/assets/files/IP-Policy-fe5925025fc0a57b1cbed64f86b26a73.pdf).
41+
- All contributors must have a Contributor License Agreement (CLA) on file with FINOS before contributions can be merged.
42+
43+
## Amendments
44+
45+
This charter may be amended by a vote of the Maintainers according to the voting process defined in [`CONTRIBUTING.md`](CONTRIBUTING.md), subject to FINOS Board approval.

‎CONTRIBUTING.md‎

Lines changed: 127 additions & 24 deletions
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,112 @@
1-
# Contributing to GitProxy
1+
# GitProxy Contribution and Governance Policies
22

3-
Thanks for your interest in contributing to GitProxy! This guide covers everything you need to get a local development environment running, understand the codebase, and submit high-quality pull requests.
3+
This document describes the contribution process and governance policies of the FINOS GitProxy project. The project is also governed by the [Linux Foundation Antitrust Policy](https://www.linuxfoundation.org/antitrust-policy/), and the FINOS [IP Policy](https://community.finos.org/assets/files/IP-Policy-fe5925025fc0a57b1cbed64f86b26a73.pdf), [Code of Conduct](https://www.finos.org/code-of-conduct), [Collaborative Principles](https://community.finos.org/docs/governance/collaborative-principles/), and [Meeting Procedures](https://community.finos.org/docs/governance/meeting-procedures/).
44

5-
For project governance, roles, and voting procedures, see the [Governance section on the website](https://git-proxy.finos.org).
5+
## Technical Charter
6+
7+
The project's [Technical Charter](CHARTER.md) defines its mission, scope, maintainer structure, intellectual property framework, and amendment process. Do not duplicate that material here.
8+
9+
## Contribution Process
10+
11+
Before making a contribution, please take the following steps:
12+
13+
1. Check whether there's already an [open issue](https://github.com/finos/git-proxy/issues) related to your proposed contribution. If there is, join the discussion and propose your contribution there.
14+
1. If there isn't already a relevant issue, [create one](https://github.com/finos/git-proxy/issues/new), describing your contribution and the problem you're trying to solve.
15+
1. Respond to any questions or suggestions raised in the issue by other developers.
16+
1. Fork the project repository and prepare your proposed contribution.
17+
1. Submit a pull request.
18+
19+
> **NOTE:** Contributors must meet FINOS contribution requirements (CLA). Please read the [FINOS Contribution Requirements](https://community.finos.org/docs/governance/Software-Projects/contribution) before opening pull requests.
20+
21+
## Governance
22+
23+
### Roles
24+
25+
The project community consists of Contributors and Maintainers:
26+
27+
- A **Contributor** is anyone who submits a contribution to the project. (Contributions may include code, issues, comments, documentation, media, or any combination of the above.)
28+
- A **Maintainer** is a Contributor who, by virtue of their contribution history, has been given write access to project repositories and may merge approved contributions.
29+
- The **Lead Maintainer** is the project's interface with the FINOS team and Board. They are responsible for approving quarterly project reports and communicating on behalf of the project. The Lead Maintainer is elected by a vote of the Maintainers.
30+
31+
### Contribution Rules
32+
33+
Anyone is welcome to submit a contribution to the project. The rules below apply to all contributions. (The key words "MUST", "SHALL", "SHOULD", "MAY", etc. in this document are to be interpreted as described in [IETF RFC 2119](https://www.ietf.org/rfc/rfc2119.txt).)
34+
35+
- All contributions MUST be submitted as pull requests, including contributions by Maintainers.
36+
- All pull requests MUST be reviewed by a Maintainer (other than the Contributor) before being merged.
37+
- Pull requests for non-trivial contributions SHOULD remain open for a review period sufficient to give all Maintainers a reasonable opportunity to review and comment on them.
38+
- After the review period, if no Maintainer has an objection to the pull request, any Maintainer MAY merge it.
39+
- If any Maintainer objects to a pull request, the Maintainers SHOULD try to come to consensus through discussion. If consensus cannot be reached, any Maintainer MAY call for a vote on the contribution using the Maintainer Voting process below.
40+
41+
#### Cross-Firm Review
42+
43+
GitProxy is used as a risk control in regulated financial institutions. To ensure broad consensus among the firms involved in project maintenance, pull requests that introduce new features (corresponding to `feat:` conventional commits), breaking changes (corresponding to a major version bump), or other changes that a Maintainer judges to be significant MUST be approved by at least one Maintainer from a different organisation than the contributing author before being merged.
44+
45+
This requirement does NOT apply to:
46+
47+
- Bug fixes
48+
- Documentation updates
49+
- Dependency patches and vulnerability remediation
50+
- CI/infrastructure maintenance
51+
- Refactoring that does not change external behaviour
52+
- Other routine upkeep
53+
54+
Maintainers contributing such changes are expected to abide by the spirit of this rule — i.e., seek cross-firm review proactively rather than requiring it to be enforced.
55+
56+
### Maintainer Voting
57+
58+
The Maintainers MAY hold votes only when they are unable to reach consensus on an issue. Any Maintainer MAY call a vote on a contested issue, after which Maintainers SHALL have 36 hours to register their votes. Votes SHALL take the form of "+1" (agree), "-1" (disagree), "+0" (abstain). Issues SHALL be decided by the majority of votes cast. If there is only one Maintainer, they SHALL decide any issue otherwise requiring a Maintainer vote. If a vote is tied, FINOS (via [[email protected]](mailto:[email protected])) SHALL cast the deciding vote.
59+
60+
The Maintainers SHALL decide the following matters by consensus or, if necessary, a vote:
61+
62+
- Contested pull requests
63+
- Election and removal of the Lead Maintainer
64+
- Election and removal of Maintainers
65+
66+
All Maintainer votes MUST be carried out transparently, with all discussion and voting occurring in public, either:
67+
68+
- in comments associated with the relevant issue or pull request, if applicable;
69+
- on the project mailing list or other official public communication channel; or
70+
- during a regular, minuted community meeting.
71+
72+
### Dispute Resolution
73+
74+
If a contribution or project decision is contested, the following escalation process applies:
75+
76+
1. Discussion in the relevant PR or issue thread to seek consensus among Maintainers.
77+
1. If unresolved, raise the matter at the next community meeting for open discussion.
78+
1. If still unresolved, any Maintainer MAY call a vote (36-hour window, majority decides per the Maintainer Voting process above).
79+
1. If the vote is tied, FINOS (via [[email protected]](mailto:[email protected])) SHALL cast the deciding vote.
80+
81+
A contributor whose pull request is closed may address the concerns raised and re-submit. If a contributor believes their contribution was unfairly rejected, they may invoke the dispute resolution process above.
82+
83+
### Maintainer Qualifications
84+
85+
Any Contributor who has made a substantial contribution to the project MAY apply (or be nominated) to become a Maintainer. The existing Maintainers SHALL decide whether to approve the nomination according to the Maintainer Voting process above.
86+
87+
### Maintainer List
88+
89+
The current Maintainer roster is recorded in [`MAINTAINERS.md`](MAINTAINERS.md). All changes to the maintainer list are managed publicly:
90+
91+
- Any addition, removal, or update MUST be submitted as a pull request to `MAINTAINERS.md`.
92+
- If the change requires a Maintainer vote (e.g. election or removal of a Maintainer or the Lead Maintainer), the vote outcome MUST be documented in, or linked from, the pull request description or comments.
93+
- This process creates a public audit trail of project leadership over time.
94+
95+
Whenever `MAINTAINERS.md` is updated with a change to maintainership, please email [[email protected]](mailto:[email protected]).
96+
97+
### Changes to this Document
98+
99+
This document MAY be amended by a vote of the Maintainers according to the Maintainer Voting process above.
100+
101+
## Contributor License Agreement (CLA)
102+
103+
All contributors must have a CLA on file with FINOS before PRs can be merged. Review the FINOS [contribution requirements](https://community.finos.org/docs/governance/Software-Projects/contribution) and submit (or have your employer submit) the required CLA via [EasyCLA](https://community.finos.org/docs/governance/Software-Projects/easycla).
104+
105+
---
106+
107+
# Development Guide
108+
109+
Thanks for your interest in contributing to GitProxy! This section covers everything you need to get a local development environment running, understand the codebase, and submit high-quality pull requests.
6110

7111
## Table of Contents
8112

@@ -92,21 +196,16 @@ git-proxy/
92196
│ ├── ui/ # React dashboard (Material-UI)
93197
│ ├── plugin.ts # Plugin base classes (PushActionPlugin, PullActionPlugin)
94198
│ └── types/ # Shared TypeScript types
95-
├── test/ # Unit and integration tests (Vitest)
96-
├── tests/e2e/ # End-to-end tests (Vitest + Docker)
199+
├── test/ # Unit, integration, and e2e tests (Vitest)
97200
├── cypress/ # UI tests (Cypress)
98-
├── localgit/ # Local git server for E2E testing (see localgit/README.md)
99201
├── packages/
100202
│ └── git-proxy-cli/ # CLI package
101203
├── plugins/ # Sample plugin packages
102204
├── website/ # Documentation site (Docusaurus)
103205
├── index.ts # CLI entry point
104-
├── docker-compose.yml # Docker Compose for E2E environment
105206
├── proxy.config.json # Default proxy configuration
106207
├── config.schema.json # JSON Schema for configuration
107-
├── vite.config.ts # Frontend build configuration
108-
├── vitest.config.ts # Unit test configuration
109-
└── vitest.config.e2e.ts # E2E test configuration
208+
└── vite.config.ts # Frontend build configuration
110209
```
111210

112211
### Key architectural concepts
@@ -169,16 +268,18 @@ npm run test-shuffle # Randomized execution order (detects test coupling)
169268
npm run test-coverage # Run with coverage report
170269
```
171270

172-
Configuration: [vitest.config.ts](vitest.config.ts)
271+
Configuration: [test/vitest.config.ts](test/vitest.config.ts)
173272

174273
Test files are organized by module:
175274

176275
```
177276
test/
277+
├── vitest.config.ts # Unit test configuration (`npm test`)
178278
├── processors/ # Proxy processor logic
179279
├── db/ # Database operations
180280
├── services/ # API and service tests
181281
├── integration/ # Cross-module integration tests
282+
├── e2e/ # End-to-end tests (Vitest + Docker, includes localgit/ and Compose)
182283
├── plugin/ # Plugin system tests
183284
├── preReceive/ # Git hook tests
184285
└── fixtures/ # Binary test data for protocol-level tests
@@ -199,7 +300,7 @@ RUN_MONGO_TESTS=true npm run test:integration
199300
docker stop mongodb-test && docker rm mongodb-test
200301
```
201302

202-
Configuration: [vitest.config.integration.ts](vitest.config.integration.ts)
303+
Configuration: [test/vitest.integration.config.ts](test/vitest.integration.config.ts), [test/integration/proxy.config.json](test/integration/proxy.config.json)
203304

204305
In CI, `RUN_MONGO_TESTS` is set automatically in the workflow that runs integration tests.
205306

@@ -217,23 +318,25 @@ npm run test:e2e
217318
npm run test:e2e:watch
218319
```
219320

220-
Configuration: [vitest.config.e2e.ts](vitest.config.e2e.ts)
321+
Configuration: [test/e2e/vitest.config.ts](test/e2e/vitest.config.ts), [test/e2e/proxy.config.json](test/e2e/proxy.config.json)
221322

222323
#### Docker Compose environment
223324

224-
The E2E environment is defined in [docker-compose.yml](docker-compose.yml) and consists of three services:
325+
The E2E environment is defined in [test/e2e/docker-compose.yml](test/e2e/docker-compose.yml) and consists of three services:
225326

226-
| Service | Port | Description |
227-
| ------------ | ---------- | ------------------------------------------------------------------------- |
228-
| `git-proxy` | 8000, 8081 | GitProxy application under test |
229-
| `mongodb` | 27017 | MongoDB 7 instance |
230-
| `git-server` | 8443 | Apache-based git HTTP server with test repos (see [localgit/](localgit/)) |
327+
| Service | Port | Description |
328+
| ------------ | ---------- | ------------------------------------------------------------------------------------------- |
329+
| `git-proxy` | 8000, 8081 | GitProxy application under test |
330+
| `mongodb` | 27017 | MongoDB 7 instance |
331+
| `git-server` | 8443 | Apache-based git HTTP server with test repos (see [test/e2e/localgit/](test/e2e/localgit/)) |
231332

232333
All services run in an isolated `git-network` Docker bridge network.
233334

234335
#### Managing the environment manually
235336

236-
When developing or debugging E2E tests, you'll often want to keep the containers running between test runs rather than letting the test script tear them down:
337+
When developing or debugging E2E tests, you'll often want to keep the containers running between test runs rather than letting the test script tear them down.
338+
339+
From the repository root, either `cd test/e2e` first or set `export COMPOSE_FILE=test/e2e/docker-compose.yml` so the following commands find the Compose file:
237340

238341
```bash
239342
# Start all services in the background
@@ -242,7 +345,7 @@ docker compose up -d
242345
# Verify all three containers are running
243346
docker compose ps
244347

245-
# Rebuild from scratch (e.g., after changing localgit/ or Dockerfile)
348+
# Rebuild from scratch (e.g., after changing test/e2e/localgit/ or Dockerfile)
246349
docker compose down -v
247350
docker compose build --no-cache
248351
docker compose up -d
@@ -314,7 +417,7 @@ docker compose exec mongodb mongosh --eval "db.adminCommand('ping')"
314417

315418
#### Generating test fixtures
316419

317-
The git server includes a data capture system that records raw git protocol data for every operation. This is useful for creating binary test fixtures (e.g., PACK files) for unit tests. See [localgit/README.md](localgit/README.md) for details on the capture system, PACK extraction tools, and fixture generation workflow.
420+
The git server includes a data capture system that records raw git protocol data for every operation. This is useful for creating binary test fixtures (e.g., PACK files) for unit tests. See [test/e2e/localgit/README.md](test/e2e/localgit/README.md) for details on the capture system, PACK extraction tools, and fixture generation workflow.
318421

319422
### UI Tests (Cypress)
320423

@@ -329,7 +432,7 @@ npm run cypress:open # Interactive test runner (recommended for development)
329432
npm run cypress:run # Headless mode (used in CI)
330433
```
331434

332-
Configuration: [cypress.config.js](cypress.config.js)
435+
Configuration: [cypress/cypress.config.js](cypress/cypress.config.js)
333436

334437
Cypress tests live in `cypress/e2e/` and use custom commands defined in `cypress/support/commands.js` (e.g., `cy.login(username, password)`).
335438

@@ -404,7 +507,7 @@ The following checks must pass before a PR can be merged:
404507

405508
### Contributor License Agreement (CLA)
406509

407-
All contributors must have a CLA on file with FINOS before PRs can be merged. Review the FINOS [contribution requirements](https://finosfoundation.atlassian.net/wiki/spaces/FINOS/pages/75530375/Contribution+Compliance+Requirements) and submit the required CLA.
510+
See the [CLA section](#contributor-license-agreement-cla) in the Governance section above.
408511

409512
## Community
410513

0 commit comments

Comments
 (0)