mirror of
https://github.com/RayLabsHQ/gitea-mirror.git
synced 2026-03-13 22:12:54 +03:00
98da7065e0
* feat: smart force-push protection with backup strategies (#187) Replace blunt `backupBeforeSync` boolean with `backupStrategy` enum offering four modes: disabled, always, on-force-push (default), and block-on-force-push. This dramatically reduces backup storage for large mirror collections by only creating snapshots when force-pushes are actually detected. Detection works by comparing branch SHAs between Gitea and GitHub APIs before each sync — no git cloning required. Fail-open design ensures detection errors never block sync. Key changes: - Add force-push detection module (branch SHA comparison via APIs) - Add backup strategy resolver with backward-compat migration - Add pending-approval repo status with approve/dismiss UI + API - Add block-on-force-push mode requiring manual approval - Fix checkAncestry to only treat 404 as confirmed force-push (transient errors skip branch instead of false-positive blocking) - Fix approve-sync to bypass detection gate (skipForcePushDetection) - Fix backup execution to not be hard-gated by deprecated flag - Persist backupStrategy through config-mapper round-trip * fix: resolve four bugs in smart force-push protection P0: Approve flow re-blocks itself — approve-sync now calls syncGiteaRepoEnhanced with skipForcePushDetection: true so the detection+block gate is bypassed on approved syncs. P1: backupStrategy not persisted — added to both directions of the config-mapper. Don't inject a default in the mapper; let resolveBackupStrategy handle fallback so legacy backupBeforeSync still works for E2E tests and existing configs. P1: Backup hard-gated by deprecated backupBeforeSync — added force flag to createPreSyncBundleBackup; strategy-driven callers and approve-sync pass force: true to bypass the legacy guard. P1: checkAncestry false positives — now only returns false for 404/422 (confirmed force-push). Transient errors (rate limits, 500s) are rethrown so detectForcePush skips that branch (fail-open). * test(e2e): migrate backup tests from backupBeforeSync to backupStrategy Update E2E tests to use the new backupStrategy enum ("always", "disabled") instead of the deprecated backupBeforeSync boolean. * docs: add backup strategy UI screenshot * refactor(ui): move Destructive Update Protection to GitHub config tab Relocates the backup strategy section from GiteaConfigForm to GitHubConfigForm since it protects against GitHub-side force-pushes. Adds ShieldAlert icon to match other section header patterns. * docs: add force-push protection documentation and Beta badge Add docs/FORCE_PUSH_PROTECTION.md covering detection mechanism, backup strategies, API usage, and troubleshooting. Link it from README features list and support section. Mark the feature as Beta in the UI with an outline badge. * fix(ui): match Beta badge style to Git LFS badge
Gitea Mirror Documentation
This folder contains engineering and operations references for the open-source Gitea Mirror project. Each guide focuses on the parts of the system that still require bespoke explanation beyond the in-app help and the main README.md.
Available Guides
Core workflow
- DEVELOPMENT_WORKFLOW.md – Set up a local environment, run scripts, and understand the repo layout (app + marketing site).
- ENVIRONMENT_VARIABLES.md – Complete reference for every configuration flag supported by the app and Docker images.
- NIX_DEPLOYMENT.md – User-facing deployment guide for Nix and NixOS.
- NIX_DISTRIBUTION.md – Maintainer notes for packaging, releases, and distribution strategy.
Reliability & recovery
- GRACEFUL_SHUTDOWN.md – How signal handling, shutdown coordination, and job persistence work in v3.
- RECOVERY_IMPROVEMENTS.md – Deep dive into the startup recovery workflow and supporting scripts.
Authentication
- SSO-OIDC-SETUP.md – Configure OIDC/SSO providers through the admin UI.
- SSO_TESTING.md – Recipes for local and staging SSO testing (Google, Keycloak, mock providers).
If you are looking for customer-facing playbooks, see the MDX use cases under www/src/pages/use-cases/.
Quick start for local development
git clone https://github.com/RayLabsHQ/gitea-mirror.git
cd gitea-mirror
bun run setup # installs deps and seeds the SQLite DB
bun run dev # starts the Astro/Bun app on http://localhost:4321
The first user you create locally becomes the administrator. All other configuration—GitHub owners, Gitea targets, scheduling, cleanup—is done through the Configuration screen in the UI.
Contributing & support
- 🎯 Contribution guide: ../CONTRIBUTING.md
- 🐞 Issues & feature requests: https://github.com/RayLabsHQ/gitea-mirror/issues
- 💬 Discussions: https://github.com/RayLabsHQ/gitea-mirror/discussions
- 🔐 Security policy & advisories: https://github.com/RayLabsHQ/gitea-mirror/security