Mirror Sync: Automated internal fork management

[coopernetes]

Related upstream: finos/git-proxy#1240

Problem

Enterprise users maintain private mirrors of public OSS repos for internal collaboration, security scanning, and code review before pushing back upstream through jgit-proxy. Currently, keeping those internal mirrors consistent with upstream is a manual/ad-hoc task outside of jgit-proxy.

There is no standard way to:

• provision the internal mirror repo automatically
• keep upstream refs represented in a predictable, non-conflicting namespace
• apply the existing validation pipeline to changes as they ingress from upstream

Proposed Design

Three interfaces in jgit-proxy-core:

• MirrorSyncTarget — upstream/internal repo coordinates + ref-translation rules + batch size
• MirrorRegistrar — SCM-provider-specific: create the internal repo if absent, resolve credentials
• MirrorSyncService — orchestrates clone → translate → push cycle (git operations only)

Initial implementation targets GitHub REST API v3 (also compatible with GHE 3.x):

• GitHubMirrorSyncTarget — with pluggable RefTranslationStrategy (identity, upstreamPrefix, upstreamSuffix)
• GitHubMirrorRegistrar — ensureRepository (idempotent POST /orgs/{org}/repos) + PAT credentials

Tasks

• Define MirrorSyncTarget, MirrorRegistrar, MirrorSyncService interfaces in jgit-proxy-core
• Implement GitHubMirrorSyncTarget with RefTranslationStrategy (identity / upstream-prefix / upstream-suffix)
• Implement GitHubMirrorRegistrar (idempotent repo creation via GitHub REST API + credential resolution)
• Implement MirrorSyncService — fetch-from-upstream → translate refs → push to internal URL in configurable batches (default 100 refs); use explicit ref specs, not --mirror
• Add optional local bare-clone cache (mirror.cache-dir) to avoid full re-clone on each sync
• Add POST /api/mirror/sync/{target} REST endpoint to trigger sync on demand (start with this rather than an internal scheduler)
• Wire mirror config into YAML (git-proxy.mirror.*) and document in CONFIGURATION.md
• Add unit tests for RefTranslationStrategy variants and GitHubMirrorRegistrar idempotency

Open Questions

• Scheduling: on-demand REST endpoint first; cron/webhook can come later
• Conflict resolution: --force-with-lease vs --force for translated refs that diverge
• GitLab / Bitbucket: interfaces designed to accommodate these without changes to MirrorSyncService
• Credentials at rest: PAT via env var acceptable for now; track against the user management plan

Related

• Depends on: nothing (standalone feature)
• Enables: Internal PR Gate (see separate issue)