Proposal: Automated MongoDB Migration Script from v1.19.2 to v2.0.0 upgrade

[re-vlad]

Is your feature request related to a problem? Please describe.
GitProxy v2.0.0 has breaking schema changes from v1.19.2 that require data migration, but no built-in migration script exists. Critical changes include:
- Repository URLs must change from https://github.com/org/repo → https://github.com/org/repo.git
- User permissions (canPush, canAuthorise) now require email addresses instead of usernames
- New fields (gitHost, owner, displayName) need to be added to existing documents

Describe the solution you'd like
To add a dedicated MongoDB migration script that:
1. Takes a database backup first;
2. Converts repository URLs to new format;
3. Adds missing fields with default values;
4. (Optional) Provides a CSV import option for username→email mapping

Describe alternatives you've considered
Manual database updates are error-prone and not recommended for production. Without a migration script, users will face data inconsistency issues when upgrading.

Additional context
no additional context

[dcoric]

Thanks for raising this. There is a real gap here, since the v2 upgrade guide itself notes that no migration files are provided and points operators at manual fixes, which does not scale beyond a handful of repos.

Before someone picks this up, a few corrections to the proposed scope based on the v2.0.0 code:

What actually changed in the schema (v1.19.2 to v2.0.0)

Diffing src/db/types.ts between the two tags:

• Repo is structurally unchanged: the same project, name, url, users.canPush, users.canAuthorise, _id fields. There is no gitHost field and no owner field on Repo in v2.0.0, so those would not be backfilled by a migration.
• User gained two optional fields, displayName? and title?. Both are nullable, so existing v1 records are valid without them and need no defaults.

What actually broke at runtime

Two things break for v1 data running on v2, and they are not quite what the issue describes:

1. Repo URL match. At push time, parseAction.ts always reconstructs the full URL with a .git suffix (the path regex in src/proxy/routes/helper.ts requires it), and getRepoByUrl is an exact $eq match on url. The backend POST /repo does not normalize URLs at create time; the .git check lives only in the NewRepo.tsx UI. So v1 repo docs whose url lacks .git silently stop matching. This is the URL fix.

2. User lookup field. v1's checkUserPushPermission looked up User by gitAccount (Git user.name). v2 looks up User by email (commit email). The canPush/canAuthorise arrays still hold GitProxy username strings in v2, the same as v1, so they do not need rewriting in normal cases. What needs to be correct on v2 is User.email for every user expected to push.

Suggested scope for a migration script

1. repos.url normalization: append .git where missing. Idempotent and fully automatic.
2. users.email audit: report users with missing, blank, or duplicate emails. These are the records that will block pushes on v2 even when ACLs look correct. Where an OIDC/AD provider is configured, an optional automatic resolution pass is feasible; otherwise an admin-supplied CSV (username,email) is a reasonable fallback. This is where the issue's CSV idea fits best.
3. repos.users.canPush / canAuthorise audit: report entries that do not resolve to any current User.username. Do not silently rewrite; surface the list so an admin can repair it.

Suggested out of scope

• Adding gitHost or owner to repos. Not in the v2 schema.
• Backfilling displayName defaults. Field is optional in v2.
• Performing the database backup from within the script. That belongs to the operator's DB tooling (Atlas snapshot, mongodump, replica set point in time recovery, etc.). A prominent warning in the script output and README is the right level.

Operational details worth pinning down up front

• Dry run by default; require an explicit flag to apply.
• Idempotent: re-running on a partially migrated database is safe.
• Emit a structured report (JSON or CSV) of what was changed and what could not be resolved.
• Place it under scripts/ and invoke via an npm script, matching the existing repo layout.